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valFORTH Video Editor 1.1 


Overview 

This editor is a powerful extension to the valFORTH system designed 
specifically for the Atari 400/800 series of microcomputers. The main purpose 
for this editor is to give the FORTH programmer an easy method of text entry to 
screens for subsequent compilation. The editor has four basic modes of opera¬ 
tion: 

1) It allows entering of new text to a FORTH screen as though 
typing on a regular typewriter. 

2) It allows quick, painless modification of any text with a 
powerful set of single stroke editing commands. 

3) It pinpoints exactly where a compilation error has occurred 
and sets up the editor for immediate correction and 
recompilation. 

4) Given the name of a precompiled word, it locates where the 
original text definition of the word is on disk, if the 
"LOCATOR" option had been selected when the word was compiled. 

The set of single stroke editing commands is a superset of the functions 
found in the MEMO PAD function of the standard Atari operating system. In 
addition to cursor movement, single character insertion/deletion, and line 
insertion/deletion, the editor supports a clear-to-end-of-1ine function, a 
split command which separates a single line into two lines, and a useful insert 
submode usually found only in higher quality word processors. 

In addition, there are provisions for scrolling both forwards and backwards 
through screens, and to save or "forget" any changes made. This is useful at 
times when text is mistakenly modified. 

Also provided is a visible edit storage buffer which allows the user to 
move, replace, and insert up to 320 lines of text at a time. This feature alone 
allows the FORTH programmer to easily reorganize source code with the added 
benefit of knowing that re-typing mistakes are avoided. Usage has shown that 
once edit-buffer management is learned, significant typing and programming 
time can be saved. 

For those times when not programming, the editor can double as a simple 
word processor for writing letters and filling other documentation needs. 

The best method for learning how to use this powerful editor is to enter the 
edit mode and try each of the following commands as they are encountered in 
the reading. 

As stated above, there are four ways in which to enter the video editor. 

The following four commands explain each of the possibilities. Note that the 
symbol "<ret>" indicates that the "RETURN" key is to be typed. 
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view screen ( scr# --- ) 

To edita screen for the first time, the "View" command is to be 
used. The video display will enter a 32 character wide mode and will 
be broken into three distinct sections. For example, 

50 V <ret> 

should give something like the display shown in fig. 1. 


Screen #50 U #Bufs: 5 


■ ( Example screen 

) ( line 0 ) 

: TEST1 

10 0 

DO 

I CR . 

LOOP ; 

( line 2 ) 

: OCTAL 

8 BASE ! ; 

( ___ ) 

: +C! 

DUP CO ROT + 
SWAP C! ; 


( 

bottom line ) 


Fig. 1 


The top window, composed of a single line, indicates in decimal 
which screen is currently being edited. One should always make a 
practice of checking this screen number to insure that editing will be 
done on the intended screen. Often times, when working with other 
number bases, the wrong screen is called up accidentally and catching 
this mistake early can save time. Also shown is the size of the edit 
buffer (described later). In this example, the buffer is five lines in 
length. This window is known as the heading window. 
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FORTH screens typically are IK (1024 characters) long. Since it is 
impossible to see an entire screen simultaneously, this editor reveals 
only half a screen at a time. There is an "upper" half and a "lower" 
half. In the center of the heading window, either a "U" or an "L" 
is displayed indicating which half of the current screen is being viewed. 
If the valFORTH system is in the half-K screen mode, neither "U" nor "L" 
is displayed since an entire half-K screen can be viewed at one time. 

In figure 1, the upper half of a full-K screen is being viewed. 

The second window (the text window) contains the text found on the 
specified screen. This window is 32 characters wide and 16 lines high. 
The white cursor (indicated by the symbol "■") will be in the upper- 
lefthand corner of the screen awaiting editing commands. 

The final five-line window found at the bottom of the screen is 
known as the buffer window. This is used for advanced editing and is 
described in greater detail in the section entitled "Buffer Management." 


L re-edit last screen ( — ) 

This command is used to re-edit the "Last" screen edited. It 
functions identically to the "V" command described above, except no 
screen number is specified. 

Example: L <ret> (re-edit screen 50) 


WHERE find location of error ( — ) 

If, when compiling code, a compilation error occurs, the WHERE 
command will enter the edit mode and position the cursor over the last 
letter of the offending word. The word can then be fixed and the screen 
can be re-compiled. Bear in mind that using the WHERE command prior to 
any occurrence of an error could give strange results. 


LOCATE locate definition cccc ( — ) 

Once source text has been compiled into the dictionary, it loses 
easy readability to all but experts of the FORTH language. Often times, 
though, it is helpful to see what the original source code was. The 
DECOMP command found in the debugger helps tremendously in this regard, 
however, some structures such as IF and DO are still difficult to follow. 
For this reason, the LOCATE command is included with the editor. 

This command accepts a word name, and if at all possible it will 
actually direct the editor to load in the screen where that word was 
defined. This is very helpful at times when one cannot remember where 
the original text was. If the screen shown in figure 1 were loaded and 
the command 

LOCATE +C! <ret> 

were given, the editor would call up screen 50 and position the cursor 
over the word which is the beginning of the definition for "+C!". 
Typically, the LOCATE command will point to , "CODE" , "CONSTANT" , 
and other defining words. 
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There is a drawback to this feature, however. In order to call up 
any word, the LOCATE command must know where the word actually is. 
Normally, when a word is compiled, there is no way of knowing where it 
was loaded from. Thus for the LOCATE command to work, each time a word 
is entered into the dictionary, three extra bytes of memory must be used 
to store this lookup information. For an application with many words, 
these extra bytes per word add up quickly, and this is not always 
desirable. For this reason, the LOCATOR command (described below) 
allows the user to enable or disable the storage of this lookup informa¬ 
tion. Only words that were compiled with the LOCATOR option selected 
can be located. If a word cannot be located, the user is warned, or if 
the DEBUGGER is loaded, the word is DECOMPed giving pseudo original code. 


LOCATOR 


enable/disable location ( ON/OFF —- ) 


In order for a word to be locatable using LOCATE, the LOCATOR option 
must have been selected prior to compiling the word. The LOCATOR option 
is selected by executing "ON LOCATOR" and deselected by executing "OFF 
LOCATOR". For example: 


ON LOCATOR 
: PLUS 

: STAR 42 EMIT ; 
OFF LOCATOR 
: NEGATE MINUS ; 


(partial view of a screen) 


Only the words PLUS and STAR can be located. NEGATE cannot be located 
since the LOCATOR option was disabled. If the DEBUGGER were loaded, 
NEGATE would be decompiled (see the debugger), otherwise, the user would 
be given a warning. The default value for LOCATOR is OFF. 


#BUFS set buffer length ( #lines — ) 

The #BUFS command allows the user to specify the length (in terms of 
number of lines) of the special edit storage buffer. The power of the 
edit buffer lies in the number of lines that can be stored in it. 

Although the default value is five, practice shows that at least 16 
lines should be set aside for this buffer. The maximum number of lines 
allowable is 320which is enough to hold 20 full screens simultaneously. 
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The following sections give a detailed description of all commands which 
the video editor recognizes. A quick reference command list can be found 
following these descriptions. t 

Cursor Movement 

When the edit mode is first entered via the "V" command, a cursor is placed 
in the upper lefthand corner of the screen. It should appear as a white block 
and may enclose a black letter. Whenever any key is typed and it is not recog¬ 
nized as an editor command, it is placed in the text window where the cursor 
appears. Likewise, any line functions (such as delete line) work on the line 
where the cursor is found. 


Ctrl a , Ctrl v, Ctrl < 5 Ctrl > move-cursor commands 

To change the current edit line or character, one of four commands 
may be given. These are known as cursor commands. They are the four 
keys with arrows on them. These keys move the cursor in the direction 
specified by the arrow on the particular key pressed. There are times, 
however, when this is not the case. 

If the current cursor line is the topmost line of the text window, 
and the "cursor-up" command is issued (by simultaneously typing "ctrl" 
and "up-arrow"), the cursor will move to the bottom line of the text 
window. Likewise, a subsequent "cursor-down" command would return the 
cursor to the topmost line of the window. Similarly, if the cursor is 
positioned on the leftmost edge and the "cursor-left" command is given, 
the cursor will "wrap" to the rightmost character ON THE SAME LINE. 

Issuing "cursor-right" will wrap back to the first character on that line. 


RETURN next-line command 

Normally, the RETURN key positions the cursor on the first character 
of the next line. If RETURN is pressed when the cursor is on the last 
line of the text window (i.e., when the last text line of the screen is 
current), the cursor is positioned in the upper lefthand corner of the 
screen. 


TAB tabulate command 

The TAB key is used to tabulate to the next fixed four column 
tabular stop to the right of the current cursor character. TABbing off 
the end of the current line simply places the cursor at the beginning of 
that same line. 


NOTE: 


Many commands in the editor will "mark" a current FORTH screen as updated 
so that any changes made can be preserved on disk. As simple cursor movement 
does not change the text window in any way, these commands never mark the 
current FORTH screen. See the section on screen management for more informa¬ 
tion. 
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Editing Commands 


Editing commands are those commands which modify the text in some 
predefined manner and mark the current FORTH screen as updated for later 
saving. 


character insert command 

When the "insert-character" command is given, a blank character 
is inserted at the current cursor location. The current character and 
all characters to the right are pushed to the right by one character 
position. The last character of the line "falls off" the end and is 
lost. . The inserted blank then becomes the current cursor character. 
This is the logical complement to the "delete-character" command 
described below. 


utL delete character command 

When the "delete-character" command is issued, the current cursor 
character is removed, and all characters to the right of the current 
cursor character are moved left one position, thus giving a "squeeze" 
effect. This is normally called "closing" a line. The rightmost 
character on the line (which was vacated) is replaced with a blank. 

This serves as the logical complement to the "insert-command" described 
above. 


* JNS line insert command 

The "line-insert" command inserts a blank line between the current 
cursor line and the line immediately above it. The current line and all 
lines below it are moved down one line to make room for the new line. 

The last line on the screen falls off the bottom and is lost. If this 
command is accidentally typed, the "oops" command (ctrl-0) described 
later can be used to recover from the mistake. Also see the "from buffer" 
command described in the section on buffer management for a similar command. 
This command serves as the logical complement to the "line-delete" command 
described below. 


shift DEL 


line delete command 


The "line-delete" command deletes the current cursor line. All 
lines below the current line are brought up one line and a blank' line 
fills the vacated bottom line of the text window. The deleted line is 
lost. If this command is accidentally issued, recovery can be made by 
issuing the "oops" command (ctrl-0) described later. Also see the 
"to-buffer" command described in the section on buffer management for a 
similar command. The "delete-line" command serves as the logical comple¬ 
ment to the "1ine-insert" command. 
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Ctrl H - erase to end of line 

The "Hack" command performs a clear-to-end-of-1ine function. The 
current cursor character and all characters to the right of it on the 
current line are blank filled. All characters blanked are lost. The 
"oops" command described later can be used to recover from an accidentally 
hacked line. 


Ctrl I insert/replace toggle 

In normal operation, any key typed which is not recognized by the 
editor as a control command will replace the current cursor character 
with itself. This is the standard replace mode. Normally, if one 
wanted to insert a character at the current cursor location, the insert 
character command would have to be issued before any text could be 
entered. If inserting many characters, this is cumbersome. 

When active, the insert submode automatically makes room for any 
new characters or words and frees the user from having to worry about 
this. When the editor is called up via the "V" command, the insert mode 
is deactivated. Issuing the insert toggle command will activate it and 
the cursor will blink, indicating that the insert mode is on. Issuing 
the command a second time will deactivate the insert mode and restore 
the editor to the replace mode. Note that while in the insert mode, all 
edit commands (except BACKS, below) function as before. 


BACKS delete previous character 

The BACKS key behaves in two different ways, depending upon whether 
the editor is in the insert mode or in the replace mode. When issued 
while in the replace mode, the cursor is backed up one position and the 
new current character is replaced with a blank. If the cursor is at the 
beginning of the line, the cursor does not move, but the cursor character 
is still replaced with a blank. 

If the editor is in the insert mode, the cursor backs up one 
position, then deletes the new current cursor character and then closes 
the line. If the cursor is at the beginning of the line, the cursor 
remains in the same position, the cursor character is deleted and the 
line closed. 


NOTE: 


As all of the above commands modify the text window in some manner, the 
screen is marked as having been changed. This is to be sure that all changes 
made are eventually saved on disk. The "quit" command described in the section 
on changing screens allows one to unmark a screen so that major mistakes need 
not be saved. 
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Buffer Management 

Much of the utility of the valFORTH editor lies in its ability to tempo¬ 
rarily save text in a visible buffer. To aid the user, it is possible to 
temporarily send text to the buffer and to later retrieve it. This storage 
buffer can hold as many as 320 lines of text simultaneously. This buffer is 
viewed through a 5 line "peephole" visible as the last window on the screen. 
Using this buffer, it is possible to duplicate, move, and easily reorganize 
text, in addition to temporarily saving a line that is about to be edited so 
that the original form can be viewed or restored if necessary. The following 
section will explain exactly how to accomplish each of these actions. 


ctH T to buffer command 

The "to-buffer" command deletes the current cursor line, but 
unlike the "delete-!ine" command where the line is lost, this command 
moves the "peephole" down and copies the line to the bottom line of the 
visible buffer window. This line is the current buffer line. The buffer 
is rolled upon each occurrence of this command so that it may be used 
repeatedly without the loss of stored text. 

For example, if the cursor is positioned on line eight of the display 
shown in figure 1 and the "to-buffer" command is issued twice, the final 
result will be as shown in figure 2. 


Ctrl F from buffer command 

The "from-buffer" command does exactly the opposite of the "to- 
buffer" command described above. It takes the current buffer line and 
inserts it between the current cursor line and the line above it. The 
cursor line and all lines below it are moved down one line with the last 
line of the text window being lost. If the cursor were placed on line 14 
of the above screen display and the "from-buffer" command were issued once 
the display in figure 3 would result. 
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fig. 2 
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Screen #50 U #Bufs: 5 j 


Current: 


( Example screen ) ( line 0 ) 

: TEST1 ( line 2 ) 

10 0 
DO 

I CR . 

LOOP ; 


: +C! 

DUP CO ROT + 

SWAP C! ; 

■ 8 BASE ! ; 

( bottom line ) 


line was 

j— — 

! 

8 BASE ! ; 


rolled to 



the top 



Current: 

: OCTAL 

j 

( — ) 


fig. 3 


If the "from-buffer" command is issued again, then lines 13 
through 15 of the text window would look like: 


Current: 


OCTAL ( — ) 

8 BASE ! ; 

{ bottom Tine ) 


fig. 4 


Note that a block of text has been moved on the screen. Larger 
blocks of text can be moved in the same manner. . 
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Ctrl K copy to buffer command 

The "copy-to-buffer" command takes the current cursor line and 
duplicates it, sending the copy to the buffer. This commands functions 
identically to the "to-buffer" command described above, except that the 
current cursor line is NOT deleted from the text window. 


Ctrl U - copy from buffer 

The "copy-from-buffer" command replaces the current cursor line with 
the current buffer line. This command functions identically to the "from- 
buffer" command described above, except that the buffer line is not inserted 
into the text window, it merely replaces the current cursor line. The 
"oops" command described below can be used to recover from accidental 
usage of this command. 


Ctrl R 


roll buffer 


The "roll-buffer" command moves the buffer "peephole" down one line 
and redisplays the visible window. If the buffer were the minimum five 
lines in length, the bottom four lines in the window would move up a line 
and the top line would "wrap" to the bottom and become the current buffer 
line. If there were more than five buffer lines, the bottom four lines 
would move up a line, the topmost line would be pushed up behind the 
peephole, and a new buffer line coming up from below the peephole would 
be displayed and made current. For example, if the buffer were five lines 
long and contained: 


Current: 


( 

Who? 

) 

( 

What? 

) 

( 

When? 

) 

( 

Where? 

) 

( 

Why? 

) 


Fig. 5 


the "roll-buffer" command gives: 


Current: 


/ 

\ 

What? 

) 

( 

When? 

) 

( 

Where? 

) 

( 

Why? 

) 

( 

Who? 

) 


Fig. 6 
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Ctrl B back-rol1-buffer command 

The "back-roll-buffer" does exactly the opposite of the "roll- 
buffer" command described above. For example, if given the buffer in 
figure 6 above, the "back-roll" command would give the buffer shown in 
figure 5. 


Ctrl C clear buffer line command 

The "clear-buffer-line" command clears the current buffer line and 
then "back-rolls" the buffer so that successive clears can be used to 
erase the entire buffer. 


NOTE: 


Any of the above commands which change the text window will mark the 
current screen as updated. Those commands which alter only the buffer window 
(such as the "roll" command) will not change the status of the current screen. 
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Changing Screens 

There are four ways in which to leave a FORTH screen. These four methods 
are: moving to a previous screen, moving to a following screen, saving the 
current screen and exiting, or simply aborting the edit session. The four 
commands allowing this are now described: 


Ctrl P previous screen command 

The "previous-screen" command has two basic functions. If the lower 
part of the current screen is being viewed in the text window, this 
command simply displays the upper portion of the screen. If the upper 
portion is already being viewed, then the "previous-screen" command saves 
any changes made to the current screen and then loads in the screen 
immediately before the current screen. The lower part of the screen 
will then be displayed. If in the half-K screen mode, however, this 
command simply changes screens. 


Ctrl N next screen command 

Like the "previous-screen" command described above, the "next-screen" 
command also has two basic functions. If the upper part of a screen is 
being viewed, this command simply displays the lower portion. If, on the 
other hand, the lower part of the screen is being edited, any changes made 
to the current screen are saved and the next screen is loaded. 


Ctrl S save command 

The "save" command saves any changes made to the current screen and 
exits the edit mode. The video screen is cleared, and the number of the 
screen just being edited is displayed for reference. Note that it is 
usually a good idea to immediately FLUSH (described in the section on 
screen management below) any unsaved screens. 


Ctrl Q quit command 

The "quit" command aborts the edit session "forgetting" any changes 
made to the text visible in the text window. Changes made on previously 
edited screens will NOT be forgotten. The "quit" command is usually 
used when either the wrong screen has been called up, or if it becomes 
desirable to start over and re-edit the screen again. 
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Special Commands 

There are four special commands in this editor which allow greater flexi¬ 
bility in programming on the valFORTH system: 


ESCAPE special key command 

The "special-key" command instructs the video editor to ignore 
any command function of the key typed next and force a character to the 
screen. For example, normally when "ctrl >" is typed, the cursor is 
moved right. By typing "ESCAPE Ctrl >" the cursor is not moved — 
rather, the right-arrow is displayed. 


Ctrl A arrow command 

When dealing with FORTH screens, it is often necessary to put the 
FORTH word (pronounced "next screen") or the ValFORTH word "==>" 

(pronounced "next screen") or the ValFORTH word "==>" (pronounced "next 
half-K screen") at the end of a screen for chaining a long set of words 
together. This command automatically places, or erases, an arrow in the 
lower right hand corner of the text window. If "—>" is already there, 
it is replaced with "==>". If "==>" is found, it is erased. (This 
command marks the screen as updated.) 


Ctrl J 


split line command 


Often times, for formatting reasons, it is necessary to "split" a 
line into two lines. The split line command takes all characters to the 
left of the cursor and creates the first line, and with the remaining 
characters of the original line, a second line is created. Graphically, 
this looks like: 

before: j The quick*brown fox jumped. | 


after: | The quick* S 

I brown fox jumped. | 

Since a line is inserted, the bottom line of the text.window is lost. 
Using the "oops" command below, however, this can be recovered. 
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Ctrl 0 oops command 

Occasionally, a line is inserted or deleted accidentally, half a 
line cleared by mistake, or some other major editing blunder is made. 
As the name implies, the "oops" command corrects most of these major 
editing errors. The "oops" command can be used to recover from the 
following commands: 


1} insert line command (shift INS) 

2 ) delete line command (shift DEL) 

3) hack command (ctrl H) 

4) to buffer command (ctrl T) 

5) from buffer command (ctrl F) 

6) copy from buffer command (ctrl U) 

7) split line command (ctrl J) 
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Screen Management 

In addition to the coranands available while in the edit mode, there are 
several other commands which are for use outside of the edit mode. Typically, 
these commands deal with entire screens at a time. 


FLUSH ( ___ ) 

When any changes are made to the current text window, the current 
screen is marked as having been changed. When leaving the edit mode 
using the "save" command, the current screen is sent to a set of internal 
FORTH buffers. These buffers are not written to disk until needed for 
other data. Thus, if no other screen is ever accessed, the buffers will 
never be saved to disk. The FLUSH command forces these buffers to be 
saved if they have been marked as being modified. 

Example: FLUSH <ret> 


EMPTY-BUFFERS ( ) 

Occasionally, screens are modified temporarily or by accident, and 
get marked as being modified. The EMPTY-BUFFERS command unmarks the 
internal FORTH buffers and fills them with zeroes so that ''bad" data are 
not saved to disk. Zero filling the buffers ensures that the next access 
to any of the screens that were in the buffers will load the 
unadulterated copy from disk. The abbreviation MTB is included in the 
valFORTH system to make the use of this command easier. 

Examples: EMPTY-BUFFERS <ret> 

MTB <ret> 


LOPY ' ( from to — ) 

To duplicate a screen, the COPY command is used. The screen "from" 
is copied to the screen "to" but not flushed. 

Example: 51 60 COPY <ret> 

(Copies screen 51 to screen 60.) 

CLEAR ( scr# — ) 

The CLEAR command fills the specified screen with blanks so that a 
clean edit can be started. The screen is then made current so that the 
L command can be used to enter the edit mode. 

Example: 50 CLEAR <ret> 

(Clears screen 50 and makes it current.) 
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va1 FORTH Video Editor 1.1 


CLEARS ( $cr# ^screens —- } 

The CLEARS command is used to clear blocks of screens at a time. 
After user verification, it starts with the specified screen and clears 
the specified number of consecutive screens. The first screen cleared 
is made current so that the L command can be used to enter the edit mode. 

Example: 25 3 CLEARS <ret> 

Clear from SCR 25 

to SCR 27 <Y/N> Y 

(Screens 25-27 are cleared. Screen 25 is made current.) 


SMOVE ( from to #screens — ) 

The SMOVE command is a multiple screen copy command used for copying 
large numbers of consecutive screens at a time. User verification is 
required by this command to avoid disastrous loss of data. All screens 
to be copied are read into available memory and the user is prompted 
to initiate the copy. This allows the swapping of disks between moves 
to make disk transfers possible. The number of screens the SMOVE command 
can copy at a time is limited only by available memory. 

Example: 50 60 5 SMOVE <ret> 

SMOVE from 50 thru 54 

to 60 thru 64 <Y/N> Y 
Insert source <RETURN> <ret> 

Insert dest. <RETURN> <ret> 

(Transfers the specified screens.) 
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valFORTH Video Editor 1.1 


Editor Command Summary 

Below is a quick reference list of all the commands which the video editor 
recognizes. 


Entering the Edit Mode: {executed outside of the edit mode) 


V ( scr# — ) 

Enter the edit mode and view the 
specified screen. 


Re-view the current screen. 


WHERE ( — ) 

Enter the edit mode and position the 
cursor over the word that caused a 
compilation error. 


LOCATE cccc ( — ) 

Enter the edit mode and position the 
cursor over the word defining "cccc". 


LOCATOR ( ON/OFF —- ) 

When ON, allows all words compiled until 
the next OFF to be locatable using the 
LOCATE command above. 


#BUFS ( #lines — ) 

Sets the length (in lines) of the storage 
buffer. The default is five. 
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Cursor Movement: (issued within the edit mode) 


Ctrl 

A 

Move cursor up one line, wrapping to the bottom 
line if moved off the top. 

Ctrl 

V 

Move cursor down one line, wrapping to the top 
line if moved off the bottom. 

Ctrl 

< 

Move cursor left one character, wrapping to the 
right edge if moved off the left. 

Ctrl 

> 

Move cursor right one character, wrapping to the 
left edge if moved off the right. 

RETURN 

Position the cursor at the beginning of the next 
line. 

TAB 


Advance to next tabular column. 

Editing Commands: 

(issued within the edit mode) 

Ctrl 

INS 

Insert one blank at cursor location, losing the 
last character on the line. 

Ctrl 

DEL 

Delete character under cursor, closing the line. 

shift 

INS 

Insert blank line above current line, losing the 
last line on the screen. 

shift 

DEL 

Delete current cursor line, closing the screen. 

Ctrl 

I 

Toggle insert-mode/replace-mode, (see full 
description of Ctrl-I). 

BACKS 


Delete last character typed, if on the same line 
as the cursor. 

Ctrl 

H 

Erase to end of line (Hack). 
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valFORTH Video Editor 1.1 


Buffer Management: (issued within the edit mode) 


Ctrl 

T 

Delete current cursor line sending it to the 
edit buffer for later use. 

Ctrl 

F 

Take the current buffer line and insert it 
above the current cursor line. 

Ctrl 

K 

Copy current cursor line sending it to the 
edit buffer for later use. 

Ctrl 

U 

Take the current buffer line and copy it to the 
current cursor line. 

Ctrl 

R 

Roll the buffer making the next buffer line 
current. 

Ctrl 

B 

Roll the buffer backwards making the previous 
buffer line on the screen current. 

Ctrl 

C 

Clear the current buffer line and perform 
a ctrl-B. 


Note: The current buffer line is last line visible on the video display. 


Changing Screens: 
Ctrl P 

Ctrl N 

Ctrl S 
Ctrl Q 

Special Keys: 

ESC 

Ctrl A 


(issued within the edit mode) 

Display the previous screen saving all changes 
made to the current text window. 

Display the next screen saving all changes made 
to the current text window. 

i 

Save the changes made to the current text window 
and end the edit session. 

Quit the edit session forgetting all changes 
made to current text window. 

(issued within the edit mode) 

Do not interpret the next key typed as any of 
the commands above. Send it directly to the 
screen instead. 

Put "==>", or erase the lower right-hand 

corner of the text window. 


Ctrl J 

Ctrl 0 


Split the current line into two lines at the 
point where the cursor is. 


Corrects any major editing blunders. 
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valFORTH Video Editor 1.1 


Screen Management: 


(executed outside of the edit mode) 


FLUSH 


Save any updated FORTH screens to disk. 


EMPTY-BUFFERS 

Forget any changes made to any screens not 
yet FLUSHed to disk. Used in "losing" major 
editing mistakes. The abbreviation MTB is 
more commonly used. 


COPY ( f rom to — ) 

Copies screen #from to screen #to. 


CLEAR ( scr# —- ) 

Blank fills specified screen. This performs 
the same functions as "WIPE" in Leo Brodie's 
book. 


CLEARS _ ( scr# Iscreens — ) 

Blank fills the specified number of screens 
starting with screen scr#. 


SMOVE ( from to #screens --- ) 

Duplicate the specified number of screens 
Starting with screen number "from". Allows 
swapping of disks before saving screens to 
screen number "to". 
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STRING UTILITIES 


The following collection of words describes the string utilities of the 
valFORTH Utilities Package. Strings have been implemented in the FORTH 
language in many different ways. Most implementations set aside space for a 
third stack -- a string stack. As strings are entered, they are moved (using 
CMOVE) to this stack. When strings are manipulated on this stack, many long 
memory moves are usually required. This method is typically much slower than 
the method implemented in valFORTH. 

Rather than waste memory space with a third stack, valFORTH uses the 
already existing parameter stack. Unlike the implementation described above, 
valFORTH does not store strings on the stack. Rather, it stores the addresses 
of where the strings can be found.* Using this method, words such as SWAP , 
DUP , PICK , and ROLL can be used to manipulate strings. Routines such as 
string sorts which work on many strings at a time are typically much faster 
since addresses are manipulated rather than long strings. In practice, we 
have found few if any problems using this method of string representation. 


String Glossary 

For the purposes of this section, a string is defined to be a sequence 
of up to 255 characters preceded by a byte indicating its length. The first 
character of the string is referenced as character one. If the length of the 
string is zero, it has no characters and is called the "null" string. In 
stack notation, strings are represented by the symbol $ and the address of the 
string is stored on the stack rather than the string itself*. 


-TEXT addrl n addr2 -- flag 

The word -TEXT compares n characters ataddressl with n characters 
at address2. Returns a false flag if the sequences match, true if they 
don’t. Flag is positive if the character sequence at addressl is alpha¬ 
betically greater than the one at address2. Flag is zero if the 
character sequences match, and is negative if the character sequence at 
addressl is alphabetically less than the one at address2. 

-NUMBER addr - d 

-NUMBER functions identically to the standard FORTH word NUMBER 
with the only difference being that -NUMBER does not abort program 
execution upon an illegal conversion. -NUMBER takes the character string 
at addr and attempts to convert it to a double number. On successful 
conversion, the value d is returned with the status variable NFLG set 
to one. On unsuccessful conversion, a double number zero is returned 
with the variable NFLG set to zero. -NUMBER is pronounced "not number". 


*Representing strings on the stack by their addresses is a very useful concept 
borrowed from MMS Forth (TRS-80), authored by Tom Dowling, and available from 
Miller Microcomputer Services, 617-653-6136. 
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NFLG 


— addr 

A variable used by -NUMBER that indicates whether the last conversion 
attempted was successful. NFLG is true if the conversion was successful; 
otherwise, it is false. 

UMOVE addrl addr2 n -- 

UMOVE is a "universal" memory move. It takes the block,of memory 
n bytes long at addrl and copies it to memory location addr2. UMOVE 
correctly uses either CMOVE or cCMOVE so that when a block of memory is 
moved onto part of itself, no data are destroyed. 

" cccc" — (at compile time) 

cccc: — addr (at run time) 

If compiling, the sequence cccc (delimited by the trailing ") is 
compiled into the dictionary as a string: 

I len I c | cl c I... I c i 

All valFORTH strings are represented in this fashion. Since a single 
byte is used to store the length, a maximum string length of 255 is 
allowed. A string with 0 length is called a "null" string. At 
execution time, " puts the address in memory where the string is 
located onto the stack. 

Note that " is IMMEDIATE, When executed outside of a colon 
definition, the string is not compiled into the dictionary, but 
is stored at PAD instead. 

Example: " This is a string" 

$C0NSTANT cccc $ -- (at compile time) 

cccc: — $ (at execution time) 

Takes the string on top of the stack and compiles it into the 
dictionary with the name cccc. When cccc is later executed, the 
address of the string is pushed onto the stack. 

Example: " Ready? <Y/N> 11 SCONSTANT VERIFY 

SVARIABLE cccc n - 

cccc: — $ 

Reserves space for a string of length n. When cccc is later 
executed, the address of the string is pushed onto the stack. 

Example: 80 $VARIABLE TEXTLINE 

$. $ - 

Takes the string on top of the stack and sends it to the current 
output device. 

Example: " Hi there" $. <ret> Hi there 

$! $ addr — 

Takes the string at second on stack and stores it at the address 
on top of stack. 

Example: " Store me!" TEXTLINE $! 
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$+ $1 $2 — $3 

Takes $2 and concatenates it with $1, leaving S3 at PAD. 

Example: " Santa " $C0NSTANT 1ST 

" Claus" SCONSTANT LAST 
1ST LAST $+ 

$. <ret> Santa Claus 

LEFTS $1 n - $2 

Returns the leftmost "n" characters of $1 as $2. S2 is stored 
at PAD. 

Example: " They" 3 LEFTS $. <ret> The 

RIGHTS $1 n — $2 

Returns the rightmost "n" characters of $1 as $2. $2 is stored 

at PAD. 

Example: " mother" 5 RIGHTS $. <ret> other 

MID$ $1 n u — $2 

Returns $2 of length u starting with the nth character of $1. 
Recall that the first character of a string is numbered as one. 

Example: " Timeout" 3 2 MID$ $. <ret> me 

LEN $ — len 

Returns the length of the specified string. 

ASC $ — c 

Returns the ASCII value of the first character of the specified 
string. 

SCOMPARE $1 $2 — flag 

Compares $1 with S2 and returns a status flag. The flag is 

a) positive if Si is greater than $2 or is equal to $2, but longer, 

b) zero if the strings match and are the same length, and c) negative 
if $1 less than $2 or if they are equal and $1 is shorter than $2. 

S= $1 $2 — flag 

Compares two strings on top of the stack and returns a status 
flag. The flag is true if the strings match and are equal in length, 
otherwise it is false. 

S< $1 S2 -- flag 

Compares two strings on top of the stack and returns a status 
flag. The flag is true if $1 is less than $2 or if $1 matches $2 but 
is shorter in length. 

$> $1 $2 — flag 

Compares two strings on top of the stack and returns a status 
flag. The flag is true if $1 is greater than $2 or if $1 matches $2 
but is longer in length. 

SAVES $1 -- $2 

As most string operations leave resultant strings at PAD, the word 
SAVE$ is used to temporarily move strings to PAD+512 so that they can 
be manipulated without being altered in the process. 

Example: " Wash" SAVE$ " ington" $+ 
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INSTR 


$1 $2 — n 

Searches $1 for first occurrence of $2. Returns the character 
position in $1 if a match is found; otherwise, zero is returned. 

Example: " FDCBA" SC0NSTANT GRADES 

GRADES " A” INSTR 1- . <ret> 4 

CHR$ c -- $ 

Takes the character "c" and makes it into a string of length one 
and stores it at PAD. 

DVAL $ ~ d 

Takes numerical string $ and converts it to a double length number. 
The variable NFLG is true if the conversion is successful, otherwise it 
is false. See -NUMBER above. 

Example: " 123” DVAL D. <ret> 123 


VAL $ - n 

Takes the numerical string $ and converts it to a single length 
number. The variable NFLG is true if the conversion is successful, 
otherwise it is false. See -NUMBER above. 

DSTR$ d - $ 

Takes the double number d and converts it to its ASCII representa¬ 
tion as $ at PAD. 

Example: 123 DSTR$ $. <ret> 123 

STR$ n -- $ 

Takes the single length number n and converts it to its ASCII 
representation as $ at PAD. 

STRINGS n $1 - $2 

Creates $2 as n copies of the first character of $1. 

#IN$ n - $ 

#IN$ has three similar but different functions. If n is positive, 
it accepts a string of n or fewer characters from the terminal. If n is 
zero, it accepts up to 255 characters from the terminal. If n is nega¬ 
tive, it returns only after accepting -n characters from the terminal. 
The resultant string is stored at PAD. 

IN$ - $ 

Accepts a string of up to 255 characters from the terminal. 

S-TB $1 — $2 

Removes trailing blanks from $1 leaving new $2. 

SXCHG $1 - $ 2 

Exchanges the contents of $1 with $2. 
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ARRAYS and their COUSINS 


All of the words described below create structures that are accessed in the 
same way, i.e., by putting the index or indices on the stack and then typing 
the structure's name. The differences are in the ways the structures are 
created. 

The concept of the array should be known from BASIC. While in fig-FORTH 
there is no standard way to implement arrays and similar structures, there 
does exist a general consensus about how this should be done. 

The point on which there is the most divergence of opinion is whether the 
first element in an array should be referred to by the index 0 or 1. We 
select 0 for the first index since this gives much cleaner code and makes 
more sense than 1 after you get used to it. (We've worked with it both ways.) 

ARRAY and CARRAY, and 2ARRAY and 2CARRAY 

The size of an array, specified when it is defined, is the number of elements 
in the array. In other words, an array defined by 

8 ARRAY BINGO 

will have 8 elements numbered 0-7. 

To access an element of an array, do 
n array-name 

to get the address of the nth element on the stack. (You will not be told 
if the number n is not a legitimate index number for the array.) For example, 

5 BINGO 

will leave the address of element number 5 in BINGO on the stack. You can 
store to or fetch from this address as you require. 

The word CARRAY defines a byte or character array. A c-array works the same 
as an array, except that you must use C@ and C! to manipulate single elements, 
rather than § and 1. 

The words 2ARRAY and 2CARRAY each take two numbers during definition of a 
2ARRAY or 2CARRAY, and 2ARRAYS and 2CARRAYS take two numbers to access an 
element. Note that when using a 2CARRAY named, say, CHESSBOARD, and a constant 
named ROOK, the two phrases 

ROOK 4 6 CHESSBOARD C! 

and 

ROOK 6 4 CHESSBOARD C! 

don't do the same thing. Also note that the phrase 
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8 8 2CARRAY CHESSBOARD 


defines a 2CARRAY of 8 x 8 = 64 elements, with both indices running from 0 to 


When an ARRAY or a CARRAY is defined, the initial values of the elements 
are undefined. 

TABLE AND CTABLE 

A cousin of ARRAY is TABLE. Example: The phrase 
TABLE THISLIST 14 , 18 , -34 , 16 , 

defines a table THISLIST of 4 elements. (The commas above are part of the 
code and must be included.) The number of elements does not have to be 
specified. The elements in THISLIST are accessed using the indices 0-3, 
the same as if it had been defined as an array. The word CTABLE works 
similarly, though using C, instead of , to compile in the numbers. Note that 
negatives won't be compiled in by a C, since in two's complement representation 
negative numbers always occupy the maximum number of bytes. 

VECTOR and CVECTOR 

The last array-type words in this package are CVECTOR and VECTOR. Vector is 
just another name for a list. These words are used when the elements of the 
array you want to create are on the stack, with the last element on top of the 
stack. You just put the number of elements on the stack and the VECTOR or 
CVECTOR, and the name you want to use. Example: 

-3 8 127 899 -43 5 VECTOR POSITIONS 

creates an array named POSITIONS with 5 elements 0-4 with -3 in element 0 
and -43 in element 4. CVECTOR works in a similar way. 


EXAMPLES: 


2 3 BINGO 1 

Stores the value 2 into element 3 of array BINGO. 


2 THISLIST @ 

Will leave the value in element 2 of table THISLIST. 
According to the definition of THISLIST above, this value 
will be -34. 


3 POSITION @ . <cr> 899 



ARRAY WORD GLOSSARY 


ARRAY cccc, n — (compiling) 

cccc: m — addr (executing) 

When compiling, creates an array named cccc with n 16-bit elements numbered 0 
thru n-1. Initial values are undefined. When executing, takes an argument, 
m, off the stack and leaves the address of element m of the array. 

CARRAY cccc, n -- (compiling) 

cccc: m -- addr (executing) 

When compiling, creates a c-array named cccc with n 8-bit elements numbered 
0 thru n-1. Initial values are undefined. When executing, takes an argument, 
m, off the stack and leaves the address of element m of the c-array. 


TABLE cccc, 
cccc: 

When compiling, 
are compiled in 
m off the stack 
m of the table. 


(compiling) 
m -- addr (executing) 

creates a table named cccc but does not allot space. Elements 
directly with , (comma). When executing, takes one argument, 
and, assuming 16-bit elements, leaves the address of element 


CTABLE cccc, 
cccc: 

When compiling, 
are compiled in 
m off the stack 
of the c-table. 


(compiling) 
m -- addr (executing) 

creates a c-table named cccc but does not allot space. Elements 
directly with C, (c-comma). When executing, takes one argument, 
and, assuming 8-bit elements, leaves the address of element m 


X! nO ... nN count addr -- 

Stores count 16-bit words, nO thru nN into memory starting at addr, with nO 
going into addr. Pronounced "extended store." 


XC1 bO ... bN count addr ~~ 

Stores count 8-bit words, bO thru bN into memory starting at addr, with bO 
going into addr. Pronounced "extended c-store." 


VECTOR cccc, nO ... nN count — (compiling) 

cccc: m -- addr (executing) 

When compiling, creates a vector named cccc with count 16-bit elements 
numbered 0-N. nO is the initial value of element 0, nN is the initial value 
of element N, and so on. When executing, takes one argument, m, off the stack 
and leaves the address of element m on the stack. 


CVECTOR cccc, bO ... bN count -- (compiling) 
cccc: m — addr (executing) 

When compiling, creates a c-vector named cccc with count 8-bit elements 
numbered 0-N. bO is the initial value of element 0, bN is the initial value 
of element N, and so on. When executing, takes an argument, m, off the stack 
and leaves the address of element m on the stack. 
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CASE STRUCTURES 


. lt often becomes necessary to make many tests upon a single number. 
Typically, this is accomplished by using a series of nested "DUP test IF" 
statements followed by a series of ENDIFs to terminate the IFs. This is 
arduous and very wasteful of memory. valFORTH contains four very .powerful 
Pascal-type CASE statements which ease programming and conserve memory. 


The CASE: structure 


Format: 


CASE: wordname 
wordO 
wordl 

wordN 


The word CASE: creates words that expect a number from 0 to 
N on the stack. If the number is zero, wordO is executed; if the 
number is one, the wordl is executed; and so on. No error checks are 
made to ensure that the case number is a legal value. 

Example: 


: ZERO Zero" ; 

: ONE One" ; 

: TWO Two" ; 

CASE: NUM 
ZERO 
ONE 

TWO ; 

0 NUM <ret> Zero 

1 NUM <ret> One 

2 NUM <ret> Two 

Note that any other number (e.g. 3 NUM) will crash the system. 
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The CASE Structure 


Format: 


: wordname 

CASE 

wordO 

wordl 

wordN 

( NOCASE wordnone } (optional) 

CASEND 


The CASE...CASEND structure is always used within a colon 
definition. Like CASE: above, it requires a number from 
0 and N. However, unlike CASE: above* boundary checks are made 
so thatan.illegal case will do nothing. If the optional NOCASE 
clause is included then wordnone is executed if an "out of bounds" 
number is used. 


Examples: 


I) : ZERO ." Zero" ; 

: ONE One" ; 

: TWO ." Two" ; 

: CHECKNUM ( n — ) 

CASE 
ZERO 
ONE 
TWO 

CASEND ; 


0 CHECKNUM <ret> Zero 

1 CHECKNUM <ret> One 

999 CHECKNUM <ret> (nothing happens) 

2 CHECKNUM <ret> Two 
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II) 


: GRADEA 

A" ; 

: GRADEB 

B" ; 

: GRADEC 

C" ; 

: GRADED 

D" ; 

: OTHER 

Failed" 


DECIMAL 

: GETGRADE ( — ) 

KEY 65 - (Convert A to 0, B to 1, etc) 

CASE 
GRADEA 
GRADES 
GRADEC 
GRADED 

NOCASE OTHER 
CASEND ; 


GETGRADE creturn and press A> A 
GETGRADE creturn and press B> B 
GETGRADE creturn and press F> Failed 
GETGRADE creturn and press D> D 


The SEL Structure 


Format: 

: wordname 

SEL - (Select) 

nl -> wordO 
n2 -> wordl 

nN > wordN 

( NOSEL wordnone ) (optional) 

SELEND 
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The SEi-SELEND structure is used when the "selection" numbers 

(nl etc.) are not sequential. This structure is somewhat slower than 
either CASE orCASE: , but is much more general. SEL is typically 
used in operations such as table driver menus where single keystroke 
commands are used. The valFORTH video editor uses the SEL structure 
to implement the many editing keystroke commands. 


Example: 


I) 


NICKEL 

nickel." ; 

DIME 

." dime." ; 

QUARTER 

." quarter." ; 

4BITS 

." fifty cent piece." 

SUSANB 

." dollar" ; 

BAD$$$ 

." wooden nickel." ; 


: MONEY-NAME ( n — ) 

." That is called a " 

SEL 

5 -> NICKEL 
10 -> DIME 
25 -> QUARTER 
50 -> 4BITS 
100 -> SUSANB 

NOSEL BAD$$$ ( this line is optional ) 

SELEND ; 


5 MONEY-NAME <ret> That is called a nickel. 

33 MONEY-NAME <ret> That is called a wooden nickel. 

25 MONEY-NAME <ret> That is called a quarter. 


The COND Structure 


Format: 


wordname 




COND 

conditionO 

« 

wordsO 

» 

condition1 

« 

words 1 

» 

conditionN 

« 

wordsn 

» 


( NOCOND wordsnone ) (optional) 

CONDEND 
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Unlike the three previous CASE structures which test for equality, 
the COND structure bases its selection upon any true conditional test 
(e.g. if n > 0 then...) COND can also be used for range cases. The 
NOCOND clause is optional and is only executed if no other condition 
passes. Only the code of the first condition that passes will be 
executed. 

Example: 

: EXAM ( score -- grade ) 

COND 


90 

>= 

« 

Grade 

of A" 

4 

» 

80 

>= 

« 

." Grade 

of B" 

3 

» 

70 

>= 

« 

." Grade 

of C" 

1 

» 

60 

>= 

« 

." Grade 

of D" 

1 

» 

NOCOND 

It 

Not 

too good" 

0 




CONDEND ; 

Note that neither « nor » are needed (nor allowed) around the 
"NOCOND" case. Also note that more than one word can be executed 
between the « and » . 
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DOUBLE NUMBER EXTENSIONS 


The following words extend the set of double number words to be as nearly 
identical as possible to the set in the book Starting FORTH . The exceptions 
are DVARIABLE and DCONSTANT which conform to the FIG standard by expecting 
initial values on the stack. 

All of the single number operations comparable to the double number operations 
below were machine coded; all of the words below (with the exception of DVARIABLE) 
have high-level run time code and so are considerably slower than their single 
number counterparts. 


DOUBLE NUMBER EXTENSION GLOSSARY 

DVARIABLE cccc d — 

cccc: -- addr 

At compile time, creates a double number variable cccc with the initial value d. 
At run time, cccc leaves the address of its value on the stack. 

DCONSTANT cccc d — 

cccc: -- d 

At compile time, creates a double number constant cccc with the initial value d. 
At run time, cccc leaves the value d on the stack. 

0 . — 0 . 

A double number constant equal to double number zero. 

1 . - 1 . 

A double number constant equal to double number one. 

D- dl d2 — d3 

Leaves dl-d2=d3. 

D0= d -- flag 

If d is equal to 0. leaves true flag; otherwise, leaves false flag. 

D= dl d2 — flag 

If dl equals d2, leaves true flag; otherwise, leaves false flag. 

D0< d -- flag 

If d is negative, leaves true flag; otherwise, leaves false flag. 

D< dl d2 -- flag 

If dl is less than d2, leaves true flag; otherwise, leaves false flag. 

D> dl d2 -- flag 

If dl is greater than d2, leaves true flag; otherwise, leaves false flag. 
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DMIN dl d2 — d3 

Leaves the minimum of dl and d2. 

DMAX dl d2 -- d3 

Leaves the maximum of dl and d2. 

D>R d — 

Sends the double number at top of stack to the return stack. 

DR> — d 

Pulls the double number at top of the return stack to the stack. 

D, d — 

Compiles the double number at top of stack into the dictionary. 

DU< udl ud2 -- flag 

If the unsigned double number udl is less than the unsigned double number ud2, 
leaves a true flag; otherwise, leaves a false flag. 

M+ dl n — d2 

Converts n to a double number and then sums with dl. 
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HIGH RESOLUTION TEXT OUTPUT 


Occasionally, the need arises to print text in high resolution graphic 
displays (8 GR.). The following set of words explains how Graphic Characters 
can be used in valFORTH programs. The Graphic-Character output routines are 
designed to function identically to the standard FORTH output operations. 
There is an invisible cursor on the high resolution page which always points 
to where the next graphic-character will be printed. As with normal text 
output, this cursor can be repositioned at any time and in various ways. 
Because of the nature of hi-res printing, this cursor can also be moved 
vertically by partial characters. This allows for super/subscripting, over¬ 
striking, and underlining. Multiple character fonts on the same line are 
also possible. 


GCINIT 

Initializes the graphic character output routines. This must be 
executed prior to using any other hi-res output words. 

GC. n — 

Displays the single length number n at the current hi-res cursor 
location. 


GC.R nl n2 -- 

Displays the single length number nl right-justified in a field 
n2 .graphic characters wide. See .R . 

GCD.R d n — 

Displays the double length number d right-justified in a field n 
graphic characters wide. See D.R . 

GCEMIT c — 

Displays the text character c at the current hi-res cursor location. 
Three special characters are interpreted by GCEMIT . The up arrow (^) 
forces text output into the superscript mode; the down arrow (^) forces 
the text into the subscript mode; and the left arrow (<-) performs a 
GCBKS command (described below). See OSTRIKE below; also see EMIT. 

GCLEN addr n — Ten 

Scans the first n characters at addr and returns the number of 
characters that will actually be displayed on screen. This is typically 
used to find the true length of a string that contains any of the non¬ 
printing special characters described in GCEMIT above. Used principally 
to aid in centering text, etc. 


GCR 


Repositions the hi-res cursor to the beginning of the next hi-res 
text 1ine. See CR . 


GCLS 


Clears the hi-res display and repositions the cursor in the upper 
lefthand corner. 
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GCSPACE 


Sends a space to the graphic character output routine. See SPACE . 

GCSPACES n — 

Sends n spaces to the graphic character output routine. See SPACES . 

GCTYPE addr n — 

Sends the first n characters at addr to the graphic character output 
routine. See TYPE . 

GC" cccc" 

Sends the character string cccc (delimited by ") to the graphic 
character output routine. If in the execution mode, this action is 
taken immediately. If in the compile mode, the character string is 
compiled into the dictionary and printed out only when executed in 
the word that uses it. See . 


GCBKS 

Moves the hi-res cursor back one character position for overstriking 
or under!ining. 

GCPOS horz vert — 

Positions the hi-res cursor to the coordinates specified. Note 
that the upper lefthand corner is 0,0. 

GC$. addr — 

Sends the string found at addr and preceded by a count byte to the 
graphic character output routine. See $. . 

SUPER 

Forces the graphic character output routine into the superscript 
mode (or out of the subscript mode). See VMI below. May be performed 
within a string by the a character. 

SUB 

Forces the graphic character output routine into the subscript 
mode (or out of the superscript mode). See VMI below. May be performed 
within a string by the * character. 

VMI n — 

Each character is eight bytes tall. The VMI command sets the number 
of eighths of characters to scroll up or down when either a SUPER or SUB 
command is issued. Normally, 4 VMI is used to scroll 4/8 or half a 
character in either direction. 

VMI# -- addr 

A variable set -by VMI. 

OSTRIKE ON or OFF - 

The GCEMIT command has two separate functions. If OSTRIKE (overstrike) 
option is OFF, the character output will replace the character at the 
current cursor position. This is the normal method of output. If the 
OSTRIKE option is ON, the new character is printed over top of the previous 
character giving the impression of an overstrike. This allows the user to 
underline text and create new characters: Example: To do underline, a 
value of, say, 2 should be used with VMI, and then the * character added 
in the string before the underline character. 
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GCBAS 


-- addr 

A variable which contains the address of the character set displayed 
by GCEMIT. To change character sets, simply store the address of your 
new character set into this variable. 

GCLFT -- addr 

A variable which holds the column position of the left margin. 
Normally two, this can be changed to obtain a different display window. 

GCRGT — addr 

A variable which holds the column position of the right margin. 
Normally 39, this can be changed to obtain a different display window. 
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MISCELLANEOUS UTILITIES 


This is a grab-bag of useful words. Here they are... 


XR/W #secs addr blk flag — 

"Extended read-write." The same as R/W except that XR/W accepts a sector 
count for multiple sector reads and writes. Starting at address addr and 
block blk, read (flag true) or write (flag false) #secs sectors from or to 
disk. 

SMOVE org des count — 

Move count screens from screen # org to screen # dest. 

The primary disk rearranging word, also used for moving sequences of screens 
between disks. This is a smart routine that uses all memory available below 
the current GR.-generated display list, with prompts for verification and 
disk swap if desired. See valFORTH Editor 1,1 documentation for further details. 

LOADS start count -- 

Loads count screens starting from screen # start. This word is used if you 
want to use words that are not chained together by --> ‘s. It will stop 
loading if a CONSOLE button is held down when the routine finishes loading 
its present screen. 

THRU start finish -- start count 

Converts two range numbers to a start-count format. Example: 

120 130 THRU PLISTS 
will print screens 120 thru 130. 

SEC n — 

Provides an n second delay. Uses a tuned do-loop. 

MSEC n — 

Provides an n millisecond delay, (approx) 

Uses a tuned do-loop. 

H->L n -- b 

Moves the high byte of n to the low byte and zero's the high byte, creating 
b. Machine code. 

L->H nl — n2 

Moves the low byte of nl to the high byte and zero's the low byte, creating 
n2. Machine code. 

H/L nl -- nl(hi) nl(lo) 

Split top of stack into two stack items: New top of stack is low byte of old 
top of stack. New second on stack is old top of stack with low byte zeroed. 
Example: HEX 1234 H/L .S <cr> 1200 0034 
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BIT b — n 

Creates a number n that has only its bth bit set. The bits are numbered 0-15, 
with zero the least significant. Machine code. 

?B IT n b — f 

Leaves a true flag if the bth bit of n is set. Otherwise leaves a false flag. 
TBIT nl b — n2 

Toggles the bth bit of nl, making n2. 

SBIT nl b — n2 

Sets the bth bit of nl, making n2. 

RBIT nl b — n2 

Resets the bth bit of nl, making n2. 

STICK n -- horiz vert 

Reads the nth stick (0-3) and resolves the setting into horizontal and 
vertical parts, with values from -1 to +1. -l ~i means up and to the left, 

PADDLE nl - n2 

Reads the nlth paddle (0-7) and returns its value n2. Machine code. 

ATTRACT f — 

If the flag is true, the attract mode is initiated. If the flag is false, 
the attract mode is terminated. 

NXTATR — 

If the system is in the attract mode, this command cycles to the next color 
setup in the attract sequence. Disturbs the timer looked at by 16TIME. 

HLDATR — 

If the system is in attract mode, zero's fast byte of the system timer so 
that attract won't cycle to next color setup for at least four seconds 
or until system timer is changed, say by NXTATR. Disturbs the timer looked 
at by 16TIME. 

16TIME — n 

Returns a 16 bit timer reading from the system clock at locations 19 and 20, 
decimal. This clock is updated 60 times per second, with the fast byte in 
20. Machine code, not fooled by carry. 

8RND — b 

Leaves one random byte from the internal hardware. Machine code. 

16RND — n 

Leaves one random word from the internal hardware. Machine code with 20 
cycle extra delay for rerandomization. 

CHOOSE ul — u2 

Randomly choose an unsigned number u2 which is less than ul. 
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CSHUFL addr n — 

Randomly rearrange n bytes in memory, starting at address addr. 

Pronounced "c-shuffle." 

SHUFL addr n - 

Randomly rearrange n words in memory, starting at address addr. Pronounced 
"shuffle." SHUFL may also be used to shuffle items directly on the stack by 
doing SP@ n SHUFL. 


H, n -- 

See DEBUG Glossary. 


A. addr — 

Print the ASCII character at addr, or if not printable, print a period. 
(Used by DUMP). 


DUMP addr n -- 

Starting at addr, dump at least n bytes (even multiple of 8) as ASCII and 
hex. May be exited early by pressing a CONSOLE button. 

BLKOP system use only 

BXOR addr count b -- 

Starting at address addr, for .count bytes, perform bit-wise exclusive or 
with byte b at each address. Useful for toggling an area of display memory 
to inverse video or a different color, and for other purposes. For instance, 
in 0 GR., do 


DCX 88 @ 280 128 BXOR 

Then do Shift-Clear to clear the screen. Pronounced "block ex or." 


BAND addr count b -- 

Starting at address addr, for count bytes, perform bit-wise AND with byte b 
at each address. Applications similar to BXOR. 

Pronounced "block and." 

BOR addr count b - 

Starting at address addr, for count bytes, perform bit-wise or with byte b 
at each address. Applications similar to BXOR. 

Pronounced "block or." 

STRIG n - flag 

Reads the button of joystick n (0-3). Leaves a true flag if the button is 
pressed, a false flag if it isn't. 

PTRIG n -- flag 

Reads the button of paddle n (0-7). Leaves a true flag if the button is 
pressed, a false flag if it isn't. 
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TRANSIENTS 


One of the more annoying parts about common releases of FORTH concerns the 
FORTH machine code assemblers. On the positive side, FORTH-based assemblers 
can be extraordinarily smart and easy to use interactively, and can compile 
on the fly as you type, rather than in multiple-pass fashion. (The 6502 
assembler provided with valFORTH is a good example of a smart, structured, 
FORTH-based assembler.) On the other hand, since the assembler loads into 
the dictonary one usually sacrifices between 3 and 4K of memory on a utility 
that is only a compilation aid, and is not used during execution. With the 
utility described below, however, you can use the assembler and then remove 
it from the dictionary when you're finished with it. 

In the directory of the Utilities/Editor disk (screen 170) you will find a 
heading of Transients. Loading this screen brings in three words: TRANSIENT, 
PERMANENT, and DISPOSE, and a few variables. It also defines a new area of 
memory called the Transient area. This area is used to load utilities like 
the assembler, certain parts of case statements, and similar constructs, that 
have one characteristic in common: They have compile-time behavior only, and 
are not used at run-time. An example will help make clear the sequence of 
operations. You may recall that on the valFORTH disk, in order to load float¬ 
ing point words you needed the assembler. Let's make a disk that has floating 
point but no assembler: 

* Boot your valFORTH disk. It can be the bare system, or your normal program¬ 
ing disk if it doesn't have the assembler already in it. 

* Insert your Utilities/Editor disk, find the Transient section in the 
directory, and load it. 

* Do MTB (EMPTY-BUFFERS) and swap in your valFORTH disk. (It is a VERY good 

idea to get into the habit of doing MTB before swapping disks.) Find the 
assembler in the directory, but before you load it, do TRANSIENT to cause it 

to be loaded into the transient dictionary area, in high memory. Now go ahead 

and load the assembler. When it is loaded, do PERMANENT so that the next 
entries will go into the permanent dictionary area, which is back where you 
started. 

* Now find and load the floating point words. 

* Finally, do DISPOSE to pinch off the links that tie the transient area 

(with the assembler in it) to the permanent dictionary, with the floating 
point words in it. Do a VLIST or two to prove it to yourself. (Note that 
there are about a half-dozen words in the assembler vocabulary in the kernel. 
These were in the dictionary on boot up and are not affected by DISPOSE.) 

You can derive great benefit from the simple recipe above, and if you study 
the Transient code a bit, you may learn even more. We offer several comments: 



* In the case of the above recipe, you didn't actually have to do PERMANENT 
and TRANSIENT because the assembler source code checks at the front to see if 
TRANSIENT exists, and does it if so. At the end if checks to see if PERMANENT 
exists, and does it if so, 'This conditional execution is accomplished with 
the valFORTH construct 

'( )( ) 

which is described in valFORTH documentation. Take a look at the assembler 
source code to see how this is done. 

* If you want to do assembly on more than one section of code, you needn't 
DISPOSE until you really finished with the assembler; or, if you have DISPOSED 
of the assembler, you can bring it back in later without harm, by the same 
method. You can also code high-level definitions, and then more assembly 
code, and so on, and only do DISPOSE when you were finished. Be sure to do 
DISPOSE before SAVE or AUTO, however, because either your system will crash 

or your SAVE'd or AUTO'd program won't work. 

The situation is slightly different with "case" words, since if you bring 
them in more than once you'll get duplicate names on the run-time words like 
(SEL), (CASE) and CASE:, which uses extra space and defeats the purpose of 
Transients. 

* If you use the Transient structures for otherpurposes, remember only to 

send code that is not used at run-time to the transient area. As an example 
of this distinction, look at the code for the "case" words on the valFORTH 
disk. Note that the '( )( ) construct is again used, but that some of 

the parts of the case constructs, for instance (SEL), stay in the permanent 
dictionary. That is because (SEL) actually ends up in the compiled code, 
while SEL does not. 

* Look at the beginning of the code for the Transient structures, and notice 
that the Transient area has been set up 4000 bytes below the display list. 

(The byte just below the display list in normal modes is pointed to by memory 
location 741 decimal, courtesy of the Atari OS.) This is usually a good place 
if only the 0 Graphics mode is used. (8 GR., for example, will over-write 
this area, crashing the system.) After DISPOSE is executed, this area is 
freed for other purposes. If you want to use a different area for Transients, 
just substitute your address into the source code on the appropriate screen. 
Remember that you must leave enough room for whatever will go into the Transient 
dictionary, and that NOTHING else must write to the area until you have cleared 
it out with DISPOSE. (This includes SMOVE, DISKC0PY1, DISKC0PY2, etc.) 

****** NOTE ***** NOTE ***** NOTE ***** NOTE ***** NOTE ****** 

In the above example, 4000 bytes have been set aside for the Transient area 
just below the 0 GR. display list. This amount of memory will generally hold 
the assembler and some case statement compiling words. REMEMBER that if you 
have relocated the buffers (see the section on Relocating Buffers) to this 
area as well, you will have a collision, and a crashed system in short order. 

To cure this, simply locate the Transient area 2113 bytes lower in memory so 
that there will be no overlap. 

****** NOTE ***** NOTE ***** NOTE ***** NOTE ***** NOTE ****** 
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0 ( Utils: XR/W ) 
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£ : XR/W ( #secs a blk# f — ) 

3 4 PICK 0 
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0 ( Utils: SMOVE ) 

1 
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4 : ATTRACT ( f — ) 
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7 : NXTATR 
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0 < Strings: -TEXT 

1 BASE @ DCX 

2 : -TEXT ( a u a — ) 

3 2DUP + SWAP 

4 DO 

5 DROP 1+ 

6 DUP 1- CO 

7 I C® - DUP 

8 IF 

9 DUP ABS 

10 / LEAVE 

11 ENDIF 

12 LOOP 

13 SWAP DROP DUP 

14 IF 1 SWAP +- ENDIF ; 
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0 ( Strings: -NUMBER ) 

1 

2 0 VARIABLE NFLG 

4 : -NUMBER ( addr — d ) 

5 BEGIN DUP C<? BL = DUP + NOT 

6 UNTIL 0 NFLG ! 0 0 ROT DUP 1+ 

7 C® 45 = DUP > R + —1 

8 BEGIN DPL ' (NUMBER) DUP C® 

9 DUP BL <> SWAP 0# AND 

10 WHILE DUP D? 46 - NFLG ! 

11 0 REPEAT DROP R> IF DMINUS 

12 ENDIF NFLG @ 

13 IF 2DR0P 0 0 ENDIF 

14 NFLG i? NOT NFLG ! ; 
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2 : ^CONSTANT ( $ ccc — ) 

3 PAD 512 + SWAP OVER $! 
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5 HERE $! HERE C® 1+ ALLOT ; 
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7 : ^VARIABLE ( len ccc — ) 

8 0 VARIABLE 

9 1- ALLOT ; 
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3 34 ( Ascii quote ) 

4 STATE ® 

5 IF ( cccc" — ) 

6 COMPILE C) WORD 

7 HERE Cl? 1+ ALLOT 
a ELSE 
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11 ENDIF ; 

12 

13 IMMEDIATE 

14 

15 ==> 


Screen: 158 

0 ( Strings: UMOVE , $! ) 

1 

2 

3 FORTH DEFINITIONS 

4 

5 : UMOVE ( a a n — ) 

6 (ROT OVER OVER U< 

7 IF 

8 ROT (CMOVE 

9 ELSE 

10 ROT CMOVE 

11 ENDIF ; 
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£ : RIGHTS ( $ n — S ) 

3 SWAP PAD <ROT PAD S! 

4 OVER <ROT OVER C© 

5 DUP 4 PICK + 

6 <ROT MIN DUP 
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8 SWAP ROT OVER OVER 
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6 1+ C@ ; 
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Placement of Tabs for valFORTH 1.1 Documentation 

The tab titles included should be cut apart and inserted into the tabs 
in the following order, starting at the highest position: 

* fig EDITOR Locate before section II 

*1.1 EXTENSIONS Locate before section IV 

*1.1 GLOSSARY Locate before section V 

* ASSEMBLER Locate before section VI 




Notes on Starting FORTH for the fig-Forth User 


April, 1982 


A very popular book on the FORTH language called Starting FORTH has recently 
been published. The author, Leo Brodie, gives an excellent description of the FORTH 
language as implemented at FORTH, Inc. fig-FORTH differs from that implementation 
in some areas, and this document explains those differences. All comments that 
apply to fig-FORTH also apply to valForth. 


BLANK = BLANKS (page 285) 

Brodie describes the word BLANK. In fig-FORTH, this word is BLANKS. 

EMPTY-BUFFERS vs. EMPTY-BUFFERS (page 283) 

Brodie's word EMPTY-BUFFERS does not necessarily change the buffers. In fia- 
FORTH, EMPTY-BUFFERS zero fills the buffers. 

CONTEXT vs. CONTEXT (page 247) 

These two words are not synonymous in the two versions. fig-FORTH uses a 
system of VOC-LINKS with CONTEXT, while FORTH, Inc. does not. " 

EXIT = ;S (page 246) 

The word EXIT, as Brodie describes it, is identical in function to ;S in fig- 
FORTH. a 

'S = SP@ (page 247) 

The word 'S in FORTH, Inc.'s is SP@ in fig-FORTH. 

EMPTY (page 84) 

Not yet implemented in fig-FORTH. 

WIPE vs. CLEAR (page 84) 

CLEAR requires a screen number while WIPE clears the last screen edited. 
ABORT" (page 103) 

Not implemented in fig-FORTH. 


PROVIDED THROUGH THE COURTESY OF VALPAR INTERNATIONAL CORPORATION; 3801 East 34th Street, 

Suite 105; Tucson, Arizona. Further distribution of this public domain document must in¬ 
clude this notice. 


?DUP = -DUP (page 103) 


The word ?DUP in FORTH, Inc.'s is -DUP in fig-FORTH. 

?STACK vs. ?STACK (page 103) 

?STACK as described by Brodie as incorrect for fig-FORTH. ?STACK in fig- 
FORTH automatically aborts if there is a stack error. 


NEGATE = MINUS, DNEGATE = DMINUS (pages 123, 178) 

The words NEGATE and DNEGATE in FORTH, Inc.'s are MINUS and DMINUS respectively 
in fig-FORTH. 


+L00P vs. +L00P (page 143) 

The word +L00P, as Brodie describes it, works differently for negative stepping 
than the +L00P in fig-FORTH. fig-FORTH always ends if the index equals the limit, 
even for negative stepping. 


PAGE = CLS (page 143) 

Brodie's PAGE is called CLS in ValForth. It has no equivalent in fig-FORTH. 


U/MOD = U/ (page 177) 

Brodie's U/MOD is U/ in fig-FORTH. 


CREATE vs. CREATE (page 209) 

Brodie's CREATE works differently from CREATE in fig-FORTH. A word using CREATE 
in fig-FORTH must unSMUDGE the header before the word can be used. The unsmudges 
headers automatically. In addition, Brodie's CREATE and fig-FORTH CREATE move different 
default values in the CFA of the created header (see below). 


CREATE = <BUILDS (page 209) 

In Brodie's chapter 11 on extending the compiler, he uses the series CREATE... 
D0ES>, In fig-FORTH, this should be <BUILDS...D0ES>. 


NUMBER vs. NUMBER (page 285) 

Brodie's NUMBER only converts numbers to double length if the double word set 
is loaded. fig-FORTH always converts numbers to double length. 


PROVIDED THROUGH THE COURTESY OF VALPAR INTERNATIONAL CORPORATION; 3801 East 34th Street, 
Suite 105; Tucson, Arizona. Further distribution of this public domain document must in¬ 
clude this notice. 



>IN = IN, H = DP (page 247) 

The variable >IN and H in Brodie's FORTH are IN and DP respectively in 
fig-FORTH. J 

VARIABLE vs. VARIABLE (page 209) 

The word VARIABLE, as Brodie describes it, accepts no value from the stack. 
fig-FORTH, on the other hand, does expect an initialization value from the stack. 


' vs. 1 (page 215) 

These words are not synonymous. 1 in Brodie is the same as ' 2~ in fig-FORTH 
(or, more properly, ' CFA). 


PROVIDED THROUGH THE COURTESY OF VALPAR INTERNATIONAL CORPORATION; 3801 East 34th Street, 
Suite 105; Tucson, Arizona. Further distribution of this public domain document must in¬ 
clude this notice. 
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VG 1 

MIH 

VGI 

p; :C;|.4 

VGI 

VG 1 

MI HUS 

VGI 

PUSH0A 

ASM 

VGi 

MOD 

VGI 

PUT 

'v G1 

VGi 

MSEC 

1 iOw 

p! !T 

MS.J 

asm 

MTS 

? t«— <* 

V d X 

PUT, 

ASM 

FP 

N 

r—r— 

8~ C 

p* : T ^q 

asm 

VGI 

N 

ASM 

r* u J! i * 

asm 

VGi 

t, * r—«, ,i 

HC A i 

VGI 

QUERY 

VGi 

■$$ 

NEXT 

ASM 

QUIT 

VG 1 

FP 

NFA 

VGI 

R 

FE 

ASM 

NFLG 

%% 

R 

VGI 

VGI 

NOCASE 

j—' c: p 

R# 

FE 

$s 

NOCOND 

CSE 

R# 

V d X 

i *r~ •» 

V X 

NOOP 

VGI 

R^'w 

i *i— i 

»j X 

ASM 

NOP , 

ASM 

R0 

VG 1 

ASM 

N03EL 

vOC 

RI¬ 

VGi 

V ■ j i 

(. i*T" 

i % iw i 

v L x 

PE IT 

C; P 

ASM 

«. m inipep 

Vg i 

rdorhg 

LLS 

ASM 

t.! *. .* *1“ 
i'l( ’) i J 

ASM 

p jtr p rr o t 

VGI 

VG i 


MSC 

r-*. r— r». r— . “t" 

'XercH . ^ 

ASM 

VGI 

o+s 

VGI 

RIGHTS 

$$ 

VED1 

OFF 

VGI 

ROL, 

ASM 

r~*»*** 

r C 

nppggT 

VGI 

ROLL 

VGI 

MSC 

ON 

VGI 

ROR, 


» If— 1 

V d X 

n» 

r< 

VGi 

pfjT 

» !«— 

V d x 

VGI 

OR 

VGI 

T*? r ~i i 

» N- 1 

V •• j X 

ASM 

ppO 

ASM 

nn r 

;\i l Li’*. 

V d X 

ASM 

ORNG 

GCS 

K j i .e 

ASM 

ASM 

ORNGRN 

>J o 


ASM 

VGI 

OSTRIKE 

HRT 

c 

rr~ 

.V .*• 

»‘4»* 

:~il J T 

v G1 

/ L*‘ 

VGI 

TT 

P v c >'*. 

V -.3 1 

Cj ?y« 

VGI 

i f *i 

V La X 

P- 

TODP 

C; ; 

TODP 

t, ir i 

V d x 

PAD 

VG 1 

SAVE 

VG 1 
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valFORTH SYSTEM INDEX 


v c.* 


r~. •** — 

V o p 

(■“' o 

T^; 

/», ,s # 

V 'Xi l 

■«« ! a 

' •’«.* o 

»*,<« i 1- * 

O C • 

* * o u 

o rr >•"** 

O Jvj 

c ; rrr,, 

ASM 

r~ 

■:*c x .» 

asm 


. ,~v r~ 

OCL 

L* O G, 

C*r-« r-». »r*. 


OC.UC.JNt/ 1 

toe 

SET COLUR 

GCS 

IF*| 

OC 5 W-" 

RSM 


C I,— 4 

O s ji ? .U i — 

V La i 

'ITT! 

**.4 »*“> !*"» 

■ ; o 

SIGH 

* »r- 
V J X 

SMCVE 

MAC 


, 

on O vc 

V C. L- ? 

SMUDGE 

VG1 

30. 

GCS 

SOUND 

GCS 

t-.l'-J ! 

O* ! 

VG1 

SPG 

VG1 

SPACE 

VG 1 

O £? Cj <■" f!T C' 

I. J 

V -Ji L 

M x T 

VG 1 

l;*i : I'-i _ t 

PISM 

r***r*c*i 

O « 

DBG 

STATE 

VG i 

«*“' **J* *? !***' * 

rise 

i ***• "***" ,W J ,*K. 

**►' 

O T H? J !\ | -'ir 

$■$ 

CTV 
•_= I A .* 

ASM 

Of iO 

OwO 

HR! 

ooor^Ou i I HE 

ASM 

SUPER 

HET 

SWRP 

VG1 

T 

c— 1— 

TP8LF 

ARY 

TASK 

VGi 

T p V , 

>*•. » fe ^ 

non 

TRY , 

ASM 

T^-' T f 

V* C 

f W a < 

i i ~. 


FE 

THEN 

VGI 

THEN .i 

RSM 

THRU 

wer 

noL 

TIB 

VGI 

TILL 

FE 

**•* » r~ 

- *Lf ’.j& L~ C 

VGI 

•r* 

FE 

"T* **'t J r r**?. ! -r* 

! n.Hr-lo j. i 

TENS 

TRAVERSE 

VGI 

* X ;’~!L/ 

V G1 

i O »'"» 

RSM 

■ri rr*<•***, 


; 

Uuo 

VP 

RSM 

•T* • ,« 

RSM 

i Yh.» 

RSM 


T* *y* r .B !T 

VGi 

v> 

VG 1 

» j 

VGI 

t ! O 

V ‘ -3 1 

1 « r***> 

Um O 

f'.nf 

•jy 

V -a I 

u> 

' ; J! X 

!j? 

VGI 

UMOVE 


UNTIL 

VG 1 

UNTIL, 

C| O **•■; 

UPdhTE 

VG £ 

USc. 

VGi 

USER 

V U X 


VED1 

VRL 

•Vif’ 

VARIABLE 

VGI 

VECTOR 

ARY 

V L. 1 O l 

VG 1 

V l*i i 

t J i—» T 

pi {If ] 

Vi'iiFr 

HRT 

VOC-LINK 

VG 1 

VOCABULARY 

VGI 

WAIT 

VGi 

WARNING 

1 5|— 4 

V >jl L 

lAinb^c. 

FE 

WHILE 

VGI 

WHILE, 

RSM 

WIDTH 

VGI 

WORD 

V vs a 

V 

pr; 

>! 

5 5 c— *! 

V «J X 

«'*« r 

ARY 

XC! 

ARY 

V? 

* IU .* 

p:~;jY! 

NOR 

V 'Ll X 

i***! n, •'* i**4 

MSC 

•.JO 

OOM 

Hw«i ; 

XSND 

GCS 

XSND4 

GCS 

YLWGRN 

La US 


VG 1 

3.< COMP ILF > 

5 If— ^ 

V -3 X 

3. > 

V U x 

ok 

VGi 




/ ■? >QO 







© 

HANDY REFERENCE CARD 

valFORTH 1J 

T.M. 


Stack inputs and outputs are shown; top of stack on right. 
This card follows usage of the Forth Interest Group 
(S.F. Bay Area); usage aligned with the Forth 78 
International Standard. 

For more info: Forth Interest Group 

P.0. Box 1105 
San Carlos, CA 94070. 


Operand Key: n,nl,. 

. 16-bit signed numbers 

d,dl,. 

. 32-bit signed numbers 

u 

16-bit unsigned number 

addr 

address 

b 

8-bit byte 

c 

7-bit ascii character value 

f 

boolean flag 

fp 

floating point number 

$ 

string 


Stack Manipulation 




DUP 

( n -- n n ) 




Duplicate top of stack. 

DROP 

( n — ) 




Throw away top of stack. 

SWAP 

( nl n2 -- n2 

nl 

) 


Reverse top two stack items. 

OVER 

( nl n2 — nl 

n2 

nl 

) 

Make copy of second item on top. 

ROT 

( nl n2 n3 -- 

n2 

n3 

nl ) 

Rotate third item to. top. 

<R0T 

( nl n2 n3 -- 

n3 

nl 

n2 ) 

Rotate top item to third. 

-DUP 

( n — n ? ) 




Duplicate only if non-zero. 

>R 

( n - ) 




Move top item to "return stack" for temporary 
storage (use caution). 

R> 

( — n ) 




Retrieve item from return stack. 

R 

( - n ) 




Copy top of return stack onto stack. 

Number 

Bases 





DECIMAL 

t - ) 




Set decimal base. 

HEX 

(- i 




Set hexadecimal base. 

BASE 

( — addr ) 




System variable containing number base. 


Arithmetic and Logical 


+ 

( nl n2 — 

sum ) 

D+ 

( dl d2 - 

sum ) 

- 

( nl n2 — 

diff ) 

* 

( nl n2 — 

prod ) 

/ 

( nl n2 -- 

quot ) 

MOD 

( nl n2 — 

rem ) 

/MOD 

( nl n2 — 

rem quot ) 

*/M0D 

( nl n2 n3 

-- rem quo 

*/ 

( nl n2 n3 

— quot ) 

MAX 

( nl n2 — 

max ) 

MIN 

( nl n2 -- 

min ) 

ABS 

( n — absolute ) 

DABS 

( d -- absolute ) 

MINUS 

( n -- -n 

) 

DMINUS 

( d-d 

) 

AND 

( nl n2 -- 

and ) 

OR 

( nl n2 — 

or ) 

XOR 

NOT 

( nl n2 -- 
( n — f ) 

xor ) 


Add. 

Add double-precision numbers. 

Subtract (nl-n2). 

Multiply. 

Divide (nl/n2). 

Modulo (i.e. remainder from division). 

Divide, giving remainder and quotient. 
Multiply, then divide (nl*n2/n3), with double- 
precision intermediate. 

Like */M0D, but give quotient only. 

Maximum. 

Minimum. 

Absolute value. 

Absolute value of double-precision number. 
Change sign. 

Change sign of double-precision number. 

Logical AND (bitwise). 

Logical OR (bitwise). 

Logical exclusive OR (bitwise). 

True if top number zero (i.e. reverses 
truth value). 


Comparison 


< 

nl n2 — f ) 

True if nl less than n2. 

> 

nl n2 — f ) 

True if nl greater than n2. 

<= 

nl n2 - -f ) 

True if nl less than or equal to n2. 

>= 

nl n2 — f ) 

True if nl greater than or equal to n2. 

= 

nl n2 — f ) 

True if top two numbers are equal. 

o 

nl n2 — f ) 

True if nl does not equal n2. 

0< 

n - f ) 

True if top number negative. 

0> 

n — f ) 

True if top number positive. 

0= 

n -- f ) 

True if top number zero (i.e. reverses 

0# 

n - f ) 

truth value. 

True if n does not equal zero. 

Memory 



0 

addr — n ) 

Replace word address by contents. 

i 

n addr -- ) 

Store second word at address on top. 

c@ 

addr -- b ) 

Fetch one byte only. 

C! 

! b addr -- ) 

Store one byte only. 

? 

’ addr -- ) 

Print contents of address. 

c? 

’ addr -- ) 

Print byte at address. 

u? 

' addr -- ) 

Print unsigned contents of address. 

+! 

[ n addr -- ) 

Add second number on stack to contents of address 
on top. 

CM0VE 

[ from to u -- ) 

Move u bytes in memory from head to head. 

<CM0VE 

1 from to u — ) 

Move u bytes in memory from tail to tail. 

FILL 

’ addr u b -- ) 

Fill u bytes in memory with b, beginning at 
address. 

ERASE 

addr u — ) 

Fill u bytes in memory with zeroes, beginning at 
address. 

BLANKS 

| addr u -- ) 

Fill u bytes in memory with blanks, beginning at 
address. 


Control Structures 

DO...LOOP do: ( end+1 start — ) 
I ( — index ) 

I' ( — index ) 

J ( — index ) 

LEAVE ( - ) 

?EXIT ( - ) 

DO... HOOP do: ( end+1 start — ) 
+loop: ( n — ) 

DO... /LOOP do: ( end+1 start -- ) 
/loop: ( u — ) 

IF...(true) if: ( f - ) 

...ENDIF 
IF...(true) 

...ELSE if: (f - ) 

...(false) 

...ENDIF 

BEGIN... until: ( f - ) 

UNTIL 

BEGIN... while: (f - ) 

WHILE 

...REPEAT 


Terminal Input - Output 

!r 

( n — ) 

£ n fieldwidth -- ) 

D- 

( d — ) 

D.R 

( d fieldwidth — } 

CR 

i ” ) 

SPACE 

( - ) 

SPACES 

(n — ) 

DUMP 

( addr u — ) 

TYPE 

( addr u — ) 

COUNT 

( addr -- addr+1 u ) 

?TERMINAL ( — f ) 

KEY 

( - C ) 

EMIT 

( c - ) 

EXPECT 

( addr n — ) 

WORD 

i c - ) 

Input 

- Output Formating 

NUMBER 

( addr -- d ) 

<t 

( - ) 

# 

( d — d ) 

#S 

( d - 0 0 ) 

SIGN 

( n d — d ) 

#> 

( d -- addr u ) 

HOLD 

( c - ) 

Disk 

Handling 

LIST 

( screen — ) 

LOAD 

( screen — ) 

BLOCK 

( block — addr ) 

B/BUF 

( — n ) 

BLK 

( — addr ) 

SCR 

( — addr ) 

UPDATE 

( - ) 

FLUSH 

( - ) 

EMPTY- 

( - ) 


Defining 

Words 


: xxx 

( - ) 


VARIABLE xxx ( n - ) 

CONSTANT xxx ( n’-i j 
xxx: ( — 

CODE xxx ( - ) 

addr ) 

n ) 

;C0DE 

( - ) 


<BUILDS... 

D0ES> 
LABEL xxx 

does : ( — 

( — addr ) 

addr ) 


Set up loop, given index range. 

Place current index value on stack. 

Used to retrieve index after a >R. 

Place index of outer DO-LOOP on stack. 

Terminate loop at next LOOP, +LOOP, or /LOOP 
LEAVE if 7TERMINAL is true (i.e. pressed). 

Like DO...LOOP, but adds stack value (instead of 
always 1 1') to index. 

Like DO... +L00P, but adds unsigned value to 
index. 

If top of stack true (non-zero), execute. (Note: 
Forth 78 uses IF...THEN.) 

Same, but if false, execute ELSE clause. (Note: 
Forth 78 uses IF...ELSE...THEN.) 

Loop back to BEGIN until true at UNTIL. (Note: 
Forth 78 uses BEGIN...END.) 

Loop while true at WHIL£;REPEAT loops uncondition¬ 
ally to BEGIN. (Note: Forth 78 uses BEGIN...IF 
...AGAIN.) 


Print number. 

Print number, right-justified in field. 

Print double-precision number 

Print double-precision number, right-justified in 

field. 

Do a carriage return. 

Type one space. 

Type n spaces. 

Print message (terminated by "). 

Dump u words starting at address. 

Type string of u characters starting at address. 
Change length-byte string to TYPE form. 

True if terminal break request present. 

Read key, put ascii value on stack. 

Type ascii value from stack. 

Read n characters (or until carriage return) from 
input to address. 

Read one word from input stream, using given 
character (usually blank) as delimiter. 


Convert string at address to double-precision number. 
Start output string. 

Convert next digit of double-precision number and 
add character to output string. 

Convert all significant digits of double-precision 
number to output string. 

Insert sign of n into output string. 

Terminate output string (ready for TYPE). 

Insert ascii character into output string. 


List a disk screen. 

Load disk screen (compile or execute). 

Read disk block to memory address. 

System constant giving disk block size in bytes. 
System variable containing current block number. 
System variable containing current screen number. 
Mark last buffer accessed as updated. 

Write all updated buffers to disk. 

Erase all buffers. 


Begin colon definition of xxx. 

End colon definition. 

Create a variable named xxx with initial value n; 
returns address when executed. 

Create a constant named xxx with value n; returns 
value when executed. 

Begin definition of assembly-language primitive 
operative named xxx. 

Used to create a new defining word, with execution¬ 
time "code routine" for this data type in assembly. 
Used to create a new defining word, with execution¬ 
time routine for this data type in higher-level Forth. 
Creates a header xxx which when executed returns its 
PFA. 
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HANDY REFERENCE CARD 

valFORTH /./ valFORTH Memory Map 


Vocabularies 

CONTEXT ( — addr ) 

CURRENT ( — addr ) 

FORTH ( — ) 

EDITOR ( — ) 

ASSEMBLER ( — ) 

DEFINITIONS ( — ) 

VOCABULARY ( — ) 

XXX 

VLIST ( — ) 


Miscellaneous and System 

( ( - ) 


FORGET xxx 

ABORT 

'xxx 

( - ) 

( - ) 

( -- addr ) 

HERE 

( — addr ) 

PAD 

( — addr ) 

IN 

( -- addr ) 

SP@ 

ALLOT 

( -- addr ) 
( n - ) 


( n — ) 


Returns address of pointer to context vocabulary 
(searched first). 

Returns address of pointer to current vocabulary 
(where new definitions are put). 

Main Forth vocabulary (execution of FORTH sets 
CONTEXT vocabulary). 

Editor vocabulary; sets CONTEXT. 

Assembler vocabulary; sets CONTEXT. 

Sets CURRENT vocabulary to CONTEXT. 

Create new vocabulary named xxx. 


STANDARD DISPLAY 
MEMORY AREA 


GENERAL BUFFER 


1 * 


PAD 


Print names of all words in CONTEXT vocabulary. 



DP- 

Begin comment, terminated by right paren on same 
line; space after ( . 

LIMIT- 

Forget all definitions back to and including xxx. 

Error termination of operation. 

Find the address of xxx in the dictionary; if used 

FIRST 

in definition, compile address. 

Returns address of next unused byte in the 
dictionary. 

Returns address of scratch area (usually 128 bytes 


$0700 

beyond HERE). 

System variable containing offset into input buffer. 

$0600 

Used, e.g., by WORD. 

Returns address of top stack item. 

$05FF 

Leave a gap of n bytes in the dictionary. 

Compile a number into the dictionary. 

$057E 



WORD BUFFER 

) 


DICTIONARY 






DISK BUFFERS 

2112 BYTES DECIMAL 
(RELOCATABLE) 



(TASK) 

KERNEL 



BOOT CODE 



ATARI FLOATING POINT 


$0080 BYTES 


USE 

PREV 

0 +ORIGIN 


USER AREA 


$0480 

$01FF 

RP 

$0100 

$00FF 

$00D4 


RETURN STACK __ 

_TERMINAL BUFFER 


ATARI FLOATING POINT 


UP 

RO 

IN 

TIB 


Z PAGE 


UP N IP W 


SO 

SP 


STACK $00BC-$0080 


SP IS X REGISTER 
RP IS STACK POINTER 
OP CPU 


Atari is a trad.rn.rti ol Atari, itic , a divisiott ol Wamrtr Corttmunlcatiotis 
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HANDY REFERENCE CARD 


valFORTH U 

T.M. 


Graphics and Color 



Debugging Utilities 

SETC0L0R 

( nl n2 n3 -- ) 


Color register nl (0...3 and 4 for background) 

DECOMP 

xxx 




is set to hue n2 (0 to 15) and luminance n3 
(0-14, even). 

CDUMP 

( addr n — ) 

SE. 

( nl n2 n3 -- ) 


Alias for SETC0L0R. 



GR. 

( n - ) 


Identical to GR. in BASIC. Adding 16 will 
suppress split display. Adding 32 will suppress 
display preclear. In addition, this GR. will 
not disturb player/missiles. 

IDUMP 

(FREE) 

( addr n — ) 


( — n ) 

P0S. 

( x y - ) 


Same as BASIC POSITION or P0S. Positions the 





invisible cursor if in a split display mode, 
and the text cursor if in 0 GR. . 

FREE 

( - ) 

POSIT 

( x y - ) 


Positions and updates the cursor, similar to 

H. 

( n - ) 




PLOT, but without changing display data. 

STACK 

( flag - ) 

PLOT 

{ x y - ) 


Same as BASIC PLOT. PLOTs point of color in 





register specified by last COLOR command, at 
point x y. 

.S 

( ... - ... ) 

DRAWTO 

( x y - ) 


Same as BASIC DRAWTO. Draws line from last 

PLOT'ted, DRAWTO'ed or POSIT'ed point to x y, 
using color in register specified by last COLOR 
command. 

U.S 

( ... - ... ) 

DR. 

( < y — ) 


Alias for DRAWTO. 

B? 

( - ) 

FIL 

( b - ) 


Fills area between last PLOT'ted, DRAWTO'ed or 
POSIT'ed point to last position set by POS., 
using the color in register b. 

Used in the form G" ccccc". Sends text cccc to 

CFALIT 

xxx ( — cfa (executing)) 
xxx ( — (compiling)) 

G" 

( - ) 






text area in non-0 Graphics mode, starting at 
current cursor position, in color of register 

Floating Point 




specified by last COLOR command prior to cccc 
being output. 

FCONSTANT 

xxx ( fp — ) 
xxx ( -- fp ) 

GTYPE 

( addr count -- ) 


Starting at addr, output count characters to 
text area in non-0 Graphics mode, starting at 
current cursor position, in color of register 
specified by last COLOR command. 

FVARIABLE 

xxx (fp -- ) 
xxx: ( addr -- ) 

LOC. 

( x y - b ) 


Positions the cursor at x y and fetches the 
data from display at that position. Like 

FDUP 

( fpl - fpl fpl ) 




BASIC LOCATE and LOC. . 

FDROP 

( fp — ) 

(G") 

l - ) 


Run-time code compiled in by G". 

FOVER 

( fp2 fpl - fp2 fpl fp2 

P0S@ 

( - x y ) 


Leaves the x and y coordinates of the cursor 
on the stack. 

FLOATING 

xxx ( -- fp ) 

CPUT 

( b — ) 


Outputs the data b to the current cursor 





position. 

FP 

xxx ( — fp ) 

CGET 

( - b ) 


Fetches the data b from the current cursor 
position. 

F@ 

{ addr -- fp } 

>SCD 

( cl - c2 ) 


Converts cl from ATASCII to its display screen 
code, c2. Example: ASCII A >SCD 88 9 C! 
will put an "A" into the upper left corner of 
the display. 

F! 

F. 

( fp addr -- ) 

( fp - ) 

SCD> 

{ cl - c2 ) 


Converts cl from display screen code to ATASCII 
c2. See >SCD. 

F? 

( addr — ) 

>BSCD 

{ addrl addr2 count — 

) 

Moves count bytes from addrl to addr2. 

F+ 

( fp2 fpl - fp3 ) 




translating from ATASCII to display screen 
code on the way. 

F- 

( fp2 fpl - fp3 } 

BSCD> 

( addrl addr2 count — 

) 

Moves count bytes from addrl to addr2. 





translating from display screen code to 

ATASCII on the way. 

F* 

( fp2 fpl - fp3 ) 

COLOR 

( b - ) 


Saves the value b in the variable CLRBYT. 

F/ 

( fp2 fpl - fp3 ) 

CLRBYT 

( — addr ) 


Variable that holds data from last COLOR 




command. 

FLOAT 

( n -- fp ) 

GREY 

— 0 PINK 

4 

BLUE - 8 GREEN - 12 


GOLD 

— 1 LVNDR 

5 

LTBLUE — 9 YLWGRN — 13 

FIX 

( fp (non-neg, less 

ORNG 

- 2 BLPRPL - 

6 

TURQ — 10 ORNGRN — 14 


than 32767.5) — n ) 

RDORNG 

- 3 PRPLBL - 

7 

GRNBL — 11 LTORNG - 15 

LOG 

( fpl - fp2 ) 



(CONSTANTS) 


SOUND 

( chan freq dist vol — 

) 

Sets up the sound channel "chan" as indicated. 
Channel: 0-3 

Frequence: 0-255, 0 is highest pitch. 

Distortion: 0-14, evens only. 

Volume: 0-15. 

Suggested mnemonic: CatFish Don't Vote 

L0G10 

EXP 

EXP10 

F0» 

( fpl - fp2 ) 

( fpl - fp2 ) 

( fpl - fp2 ) 

1 fp — flag ) 

SO. 

( chan freq dist vol — 

) 

Alias of SOUND. 

FILTER! 

( n - ) 


Stores n in the audio control register and into 
the valFORTH shadow register, AUDCTL. Use 

F* 

( fp2 fpl -- flag ) 




AUDCTL when doing bit manipulation, then do 
FILTER!. 

F> 

( fp2 fpl -- flag ) 

AUDCTL 

( — addr ) 


A variable containing the last value sent to the 
audio control register by FILTER!. 

F< 

( fp2 fpl - flag ) 

XSND 

( n — ) 


Silences channel n. 

FLITERAL 

( fp - ) 

XSND4 

( -- ) 


Silences all channels. 

Text Output and Disk Preparation 

Operating System 

S: 

( flag — ) 


If flag is true, enables handler that sends 
text to text screen. If false, disables the 
handler. (See PFLAG in main glossary.) 

OPEN 

( addr nO nl n2 — n3 ) 


P: 

( flag - ) 


If flag is true, enables handler that sends 
text to printer. If false, disables the 

CLOSE 

( n - ) 


- 


handler. (See PFLAG in main glossary) 

PUT 

( bl n — b2 ) 

BEEP 

( - ) 


Makes a raucous noise from the keyboard. 



ASCII 

{ c, -- n (executing) 

) 

Converts next character in input stream to 

GET 

( n - bl b2 ) 


( c, — (compiling) 

) 

ATASCII code. If executing, leaves on stack. 

If compiling, compiles as literal. 

GETREC 

( addr nl n2 — n3 ) 

EJECT 

( - ) 


Causes a form feed on smart printers if the 
printer handler has been enabled by ON P:. 

May need adjustment for dumb or nonstandard 

PUTREC 

( addr nl n2 -- n3 ) 




printers. 

STATUS 

( n — b ) 

LISTS 

( start count — ) 


From start, lists count screens. May be aborted 
by CONSOLE button at the end of a screen. 

DEVSTAT 

( n — bl b2 b3 ) 

PL I ST 

( scr - ) 


Lists screen scr to the printer, then restores 

SPECIAL 

( bl b2 b3 b4 b5 b6 




former printer handler status. 


b7 b8 — b9 ) 

PL ISTS 

( start cnt — ) 


From start, lists cnt screens to printer three 
to a page, then restores former printer handler 
status. May be aborted by CONSOLE button at 
the end of a screen. 

RS232 

( - ) 

FORMAT 

( - ) 


With prompts, will format a disk in drive of 
your choice. 




Does a decompilation of the word xxx if it can 
be found in the active vocabularies. 

A character dump from addr for at least n 
characters. (Will always do a multiple of 16.) 

A numerical dump in the current base for at 
least n characters. (Will always do a multiple 
of 8.) 

Leaves number of bytes between bottom of display 
list and PAD. 

Does (FREE) and then prints the stack and 
"bytes". 

Prints n in HEX, leaves BASE unchanged. 

If flag is true, turns on visible stack. 

If flag is false, turns off visible stack. 

Does a signed, nondestructive stack printout, 

TOS at right. Also sets visible stack to do 
signed printout. 

Does unsigned, nondestructive stack printout, 

TOS at right. Also sets visible stack to do 
unsigned printout. 

Prints the current base, in decimal. Leaves 
BASE undisturbed. 

Gets the cfa (code field address) of xxx. If 
executing, leaves it on the stack; if compiling, 
compiles it as a literal. 


The character string is assigned the constant 
value fp. When xxx is executed, fp will be 
put on the stack. 

The character string xxx is assigned the 
initial value fp. When xxx is executed, the 
addr (two bytes) of the value of xxx will be 
put on the stack. 

Copies the fp number at top-of-stack. 

Discards the fp number at top-of-stack.) 

Copies the fp number at 2nd-on-stack to 
top-of-stack. 

Attempts to convert the following string, xxx, 
to a fp number. 

Alias for FLOATING. 

Fetches the fp number whose address is at 
top-of-stack. 

Stores fp into addr. Remember that the 
operation will take six bytes in memory. 

Type out the fp number at top-of-stack. 

Ignores the current value in BASE and uses 
base 10. 

Fetches a fp number from addr and types it out. 
Replaces the two top-of-stack fp items, fp2 and 
fpl, with their fp sum, fp3. 

Replaces the two top-of-stack fp items fp2 and 
fpl, with their difference, fp3*fp2-fpl. 

Replaces the two top-of-stack fp items fp2 and 
fpl, with their product, fp3. 

Replaces the two top-of-stack fp items fp2 and 
fpl, with their quotient, fp3=fp2/fpl. 

Replaces number at top-of-stack with its fp 
equivalent. 

Replaces fp number at top-of-stack, constrained 
as indicated, with its integer equivalent. 
Replaces fpl with its base e logarithm, fp2. 

Not defined for fpl negative. 

Replaces fpl with its base 10 decimal logarithm, 
fp2. Not defined for fpl negative. 

Replaces fpl with fp2, which equals e to the 
power fpl. 

Replaces fpl with fp2, which equals 10 to the 

r awer fpl. 

f fp is equal to floating-point 0, a true 
flag is left. Otherwise, a false flag is left. 
If fp2 is equal to fpl, a true flag is left. 
Otherwise, a false flag is left. 

If fp2 is greater than fpl, a true flag is 
left. Otherwise, a false flag is left. 

If fp2 is less than fpl, a true flag is left. 
Otherwise, a false flag is left. 

If compiling, then compile the fp stack value 
as a fp literal. 


This word opens the device whose name is at 
addr. The device is opened on channel nO with 
AUX1 and AUX2 as nl and n2 respectively. The 
device status byte is returned as n3. 

Closes channel n. 

Outputs byte bl on channel n, returns status 
byte b2. 

Gets byte bl from channel n, returns status 
byte b2. 

Inputs record from channel n2 up to length nl. 
Returns status byte n3. 

Outputs nl characters starting at addr through 
channel n2. Returns status byte n3. 

Returns status byte b from channel n. 

From channel nl gets device status bytes bl and 
b2, and normal status byte b3. 

Implements the Operating System "Special" 
command. AUX1 through AUX6 are bl through b6 
respectively, command byte is b7, channel number 
is b8. Returns status byte b9. 

Loads the Atari 850 drivers into the dictionary 
(approx 1.8K). 
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valFORTH U1 


valFORTH 6502 Assembler 

ASSEMBLER ( — ) 

CODE xxx ( — ) 

Cl ( — ) 

END-CODE ( — ) 

SUBROUTINE xxx ( — ) 

■.CODE ( — ) 


Calls up the assembler vocabulary for subsequent 
assembly language programming. 

Enters the new word "xxx" into the dictionary 
as machine language word and calls up the 
assembler vocabulary for subsequent assembly 
language programming. . 

Terminates an assembly language definition by 
performing a security check and setting the 
CONTEXT vocabulary to the same as the CURRENT 
vocabulary. 

A commonly used synonym for the word C; above. 
The word C; is reconmended over END-CODE. 

Enters the new word "xxx" into the dictionary 
as machine language subroutine and calls up 
the assembler vocabulary for subsequent assembly 
language programing. 

When the assembler is loaded, puts the system 
into the assembler vocabulary for subsequent 
assembly language programming. See main 
glossary for further explanation. 




Control Structures 

IF, ( flag — addr 2 ) 

ELSE, ( addr 2 — addr 3 ) 

ENDIF, ( addr 2/3 — ) 


Begins a machine language control structure 
based on the 6502 status flag on top of the 
stack. Leaves an address and a security check 
value for the ELSE, or ENDIF, clauses below, 
"flag" can be EQ , NE , CC , CS , VC , VS , 

MI , or PL . Command forms: 


...flag..IF,..if-true..ENDIF,...all... 

...flag..IF,..if-true.. 

ELSE,..if-false..ENDIF,..all... 

Used in an IF, clause to allow for execution 
of code only if IF, clause is false. If the IF, 
clause is true, this code is bypassed. 

Used to terminate an IF, control structure 
clause. Additionally, ENDIF, resolves all 
fnrusrH *-pfprpnr.ps. See IF, above for command 


form. 


BEGIN, 


UNTIL, 

WHILE, 

REPEAT, 

AGAIN, 


addr 1 ) Begins machine language control structures of 

the following forms: 

...BEGIN,...AGAIN,... 

...BEGIN,...flag..UNTIL,... 

.BEGIN,...flag..WHILE,..while-true..REPEAT,... 
where "flag" is one of the 6502 statuses: EQ , 
NE , CC , CS , VC , VS , MI , and PL . 
addr 1 flag -— ) Used to terminate a post-testing BEGIN, clause 

thus allowing for conditional looping of a 
program segment while "flag" is false, 
addr 1 flag —- addr 4 ) Used to begin a pre-testing BEGIN, clause thus 
allowing for conditional looping of a program 
segment while "flag" is true. 

■ addr 4 ... ) Used to terminate a pre-testing BEGIN,..WHILE, 

clause. Additionally, REPEAT, resolves all 
forward addresses of the current WHILE, clause. 

; addr 1 — ) Used to terminate an unconditional BEGIN, 

clause. Execution cannot exit this loop unless 
a JMP, instruction is used. 


Parameter Passing (These routines must be jumped to.) 


NEXT 

( — addr ) 

PUSH 

( — addr ) 

PUSHOA 

( — addr ) 

PUT 

( — addr ) 

PUTOA 

( — addr ) 

BINARY 

( — addr ) 

POP and 
POPTWO 

( — addr ) 

SETUP 

( — addr ) 

N 

( — addr ) 

Opcodes 

( various —• 


Aliases 


NXT, 

* 

NEXT JMP, 

PSH, 

= 

PUSH JMP, 

PUT, 

= 

PUT JMP, 

PSHA, 

r 

PUSHOA JMP 

PUTA, 

3 

PUTOA JMP, 

POP, 

* 

POP JMP, 


Transfers control to the next FORTH word to be 
executed. The parameter stack is left unchanged. 
Pushes a 16 bit value to the parameter stack 
whose low byte is found on the 6502 return 
stack and whose high byte is found in the 
accumulator. 

Pushes a 16 bit value to the parameter stack 
whose low byte is found in the accumulator and 
whose high byte is zero. 

Replaces the value currently on top of the 
parameter stack with the 16 bit value whose 
low byte is found on the 6502 stack and whose 
high byte is in the accumulator. 

Replaces the value currently on top of the 
parameter stack with the 16 bit value whose 
low byte is in the accumulator and whose high 
byte is set to zero. 

Drops the top value of the parameter stack 
and then performs a PUT operation described 
above. 

POP drops one value from the parameter stack. 
POPTWO drops two values from the parameter 
stack. 

Moves one to four values to the N scratch area 
in the zero page and drops all values moved 
from the parameter stack. 

Points to a nine-byte scratch area in the zero 


page 

beginning at 

N-l 

and going to 

N+7. 

CLI, 

ADC, 

AND, 

ASL, 

BIT, 

BRK, 

CLC, 

CLD, 

CLV, 

CMP, 

CPX, 

CPY, 

DEC, 

DEX, 

DEY, 

EOR, 

INC, 

INX, 

INY, 

JSR, 

JMP, 

LDA, 

LDX, 

LDY. 

LSR, 

NOP, 

ORA, 

PHA. 

PHP, 

PLA, 

PLP, 

ROL. 

ROR, 

RTI, 

RTS, 

SBC. 

SEC, 

SED, 

SEI, 

STA. 

STX, 

TAX, 

TAY, 

TSX. 

TXA, 

TXS, 

TYA, 



POP2, 

= POPTWO JMP. 

XL, 

= XSAVE LDX, 

XS, 

= XSAVE STX, 

THEN, 

= ENDIF, 

END, 

= UNTIL, 
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SOFTWARE SYSTEM 

EDJTOfl 1:1 COMMAND SUMMARY 

Below is a quick reference list of all the commands which the video editor 
recognizes. 


Entering the Edit Mode (executed outside of the edit mode) 


LOCATE cccc ( — ) 


( ON/OFF — ) 


* Enter the edit mode and view the specified screen. 

* Re-view the current screen. 

* Enter the edit mode and position the cursor over 
the word that caused a compilation error. 

Enter the edit mode and position the cursor over 
the word "cccc" where it is defined. 

When ON, allows all words compiled until the next 
OFF to be locatable using the LOCATE command above. 
Sets the length (in lines) of the storage buffer. 
The default is five. 


Cursor Movement (issued within the edit mode) 


* Move cursor up one line, wrapping to the bottom line 
if moved off the top. 

* Move cursor down one line, wrapping to the top line 
if moved off the bottom. 

* Move cursor left one character, wrapping to the 
right edge if moved off the left. 

* Move cursor right one character, wrapping to the 
left edge if moved off the right. 

Position the cursor at the beginning of the next 
line. 

Advance to next tabular column. 


Editing Commands (issued within the edit mode) 


Insert one blank at cursor location, losing the 
last character on the line. 

Delete character under cursor, closing the line. 

* Insert blank line above current line, losing the 
last line on the screen. 

* Delete current cursor line, closing the screen. 
Toggle insert-mode/replace-mode. 

(see full description of ctrl-I). 

* Delete last character typed, if on the same line 
as the cursor. 

Erase to end of line (Hack). 


Buffer Management ( issued within the edit mode) 

Ctrl T Delete current cursor line sending 

it to the edit buffer for later use. 

Ctrl F Take the current buffer line and insert it 

above the current cursor line. 

Ctrl K Copy current cursor line sending it to the 

edit buffer for later use. 

Ctrl U Take the current* buffer line and copy it 

to the current cursor line. 

Ctrl R Roll the buffer making the topmost buffer 

line current. 

Ctrl B Roll the buffer backwards making the fourth 

* buffer line on the screen current. 

Ctrl C Clear the current* buffer line and performs 

a ctrl-B. 

*Note: The current buffer line is bottommost on the video display. 

Changing Screens (issued within the edit mode) 

Ctrl P Display the previous screen saving all 

changes made to the current screen. 

Ctrl N Display the next screen saving all changes 

made to the current screen. 

Ctrl S * Save the changes made to the current screen 

and end the edit session. 

Ctrl Q * Quit the edit session forgetting all changes 

made to the current screen. 

Special Keys (issued within the edit mode) 

ESC * Do not interpret the next key typed as any 

of the commands above. Send it directly to 
the screen instead. 

Ctrl A Put the arrow ("next screen") in the 

lower-right-hand corner of the screen unless 
it is already there, in which case remove it. 

Ctrl J Split the current line into two lines at the point 

where the cursor is. 

Ctrl 0 Corrects any major editing blunders. 

Screen Management (executed outside of the edit mode) 


FLUSH 
EMPTY- 
BUFFERS 
COPY 
CLEAR 
CLEARS 


( — ) * Save any updated FORTH screens to disk. 

( — ) * Forget any changes made to any screens not yet 

FLUSHed to disk. 

( from to -- ) * Copies screen #from to screen #to. 

( scr# — ) * Blank fills specified screen. 

( scr# Iscreens — ) Blank fills the specified number of screens start¬ 
ing with screen scr#. 

( from to #screens -- ) Duplicate the specified number of screens Starting 
with screen number "from". 


* EDITOR 1.0 COMMAND 
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SOFTWARE SYSTEM 

GENERAL UTILITIES 


Case Structures 

CASE: structure 
Format: 


CASE Structure 

Format: 

: wordname 

CASE 

wordO 

wordl 


wordN 

( NOCASE wordnone ) 
CASEND 


SEL Structure 
Format: 


wordname 

: wordname 

wordO 



wordl 

SEL 



nl 

-> wordO 

wordN ; 

n 2 

-> wordl 


nN 

> wordN 


( NOSEL 

wordnone 


SELEND 

COND Structure 
Format: 

: wordname 


COND 

conditionO « wordsO » 
condition 1 « words 1 » 

conditionN « wordsn » 
( NOCOND wordsnone ) 

CONDEND 



Miscellaneous Utilities 


XR/W 

( *secs addr blk flag — 

) "Extended read-write." The same as R/W except 
that XR/W accepts a sector count for multiple 
sector reads and writes. Starting at address 
addr and block blk, read (flag true) or write 
(flag false) #secs sectors from or to disk. 

LOADS 

( start count -- ) 

Loads count screens starting from screen if 
start. 

THRU 

( start finish -- 

start count 

Converts two range numbers to a start-count 
) format. 

SEC 

( n — ) 

Provides an n second delay. Uses a tuned 
do-loop. 

MSEC 

( n — ) 

Provides an n millisecond delay, (approx) 

Uses a tuned do-loop. 

H->L 

( nl — n 2 ) 

Moves the high byte ofnlto the low byte and 
zero's the high byte, creating n2. Machine 
code. 

L->H 

( nl — n 2 ) 

Moves the low byte of nl to the high byte and 
zero's the low byte, creating n2. Machine code 

H/L 

( nl — nl(hi) nl(lo) ) 

Split top of stack into two stack items: 

New top of stack is low byte of old top of 
stack. New second on stack is old top of 
stack with low byte zeroed. 

BIT 

( b — n ) 

Creates a number n that has only its bth bit 
set. The bits are numbered 0-15. 

?B IT 

( n b — f ) 

Leaves a true flag if the bth bit of n is set. 
Otherwise leaves a false flag. 

TBIT 

( nl b -- n 2 ) 

Toggles the bth bit of nl, making n2. 

SB IT 

( nl b -- n 2 ) 

Sets the bth bit of nl, making n2. 

RBIT 

( nl b -- n 2 ) 

Resets the bth bit of nl, making n2. 

STICK 

( n — horz vert ) 

Reads the nth stick (0-3) and resolves the 
setting into horizontal and vertical parts, 
with values from -1 to + 1 . -1 -1 means up 
and to the left. 

PADDLE 

( nl - n 2 ) 

Reads the nlth paddle (0-7) and returns its 
value n2. Machine code. 

16TIME 

( -- n ) 

Returns a 16 bit timer reading from the system 
clock at locations 19 and 20, decimal. 

8 RND 

( -- b ) 

Leaves one random byte from the internal 
hardware. Machine code. 

16RND 

( — n ) 

Leaves one random word from the internal 
hardware. Machine code with 20 cycle extra 
delay for rerandomization. 

CHOOSE 

( ul - u2 ) 

Randomly choose an unsigned number u2 which 
is less than ul. 

CSHUFL 

( addr n — ) 

Randomly rearrange n bytes in memory, start¬ 
ing at address addr. 

SHUFL 

( addr n — ) 

Randomly rearrange n words in memory, start¬ 
ing at address addr. 

DUMP 

( addr n -- ) 

Starting at addr, dump at least n bytes (even 
multiple of 8 ) as ASCII and hex. May be 
exited early by pressing a CONSOLE button. 

BXOR 

( addr count b -- ) 

Starting at address addr, for count bytes, 
perform bit-wise exclusive OR with byte b at 
each address. 

BAND 

( addr count b — ) 

Starting at address addr, for count bytes, 
perform bit-wise AND with byte b at each 
address. 

BOR 

( addr count b - ) 

Starting at address addr, for count bytes, 
perform bit-wise OR with byte b at each address. 

STRIG 

( n — flag ) 

Reads the button of joystick n (0-3). 

PTRIG 

( n -- flag ) 

Reads the button of paddle n (0-7). 
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Strings 


UMOVE 

( addrl addr 2 n -- 

" ccc" 

( -- ) 


( -- addr ) 


SCONSTANT xxx 

( $ -- 

xxx: 

( - S 


SVARIABLE 

xxx 

( n — 

) 


xxx: 

( - 

S ) 

$. 

t $ - 

- ) 


$! 

( $ addr — ' 

) 

$+ 

( si 

52 - 

S3 ) 

LEFTS 

( s; 

n -- 

S2 ) 

RIGHTS 

( si 

n -- 

S2 ) 

MIDS 

( si 

n u • 

- S2 

LEN 

( s - 

- len ) 


ASC 

( s - 

- c ) 


SCOMPARE 

( si 

S2 — 

flag 

$= 

( si 

$2 - 

flag 

$< 

( si 

$2 - 

flag 

$> 

( si 

S2 - 

flag 

SAVES 

( si 

- $2 

) 

INSTR 

( si 

$2 - 

n ) 

CHRS 

( c 

-- S ) 


DSTRS 

( d 

-- s ) 


STRS 

( n 

- $ ) 


STRINGS 

( n 

SI - 

S2 } 

# I NS 

( n - 

- $ ) 



INS 

( - S ) 

S-TB 

( SI -- S2 ) 

SXCHG 

! SI - S2 ) 

Array 

Word Glossary 

ARRAY 

xxx ( n -- ) 

xxx:( m — addr ) 


CARRAY 

xxx ( n -- 


xxx:( m -- addr 


TABLE 

xxx ( — ) 


xxx:( m -- addr ) 


CTABLE 

xxx ( — 
xxx:( m — 

) 

addr ) 

VECTOR 

xxx (nO .. 

. nN count .. 


xxx: ( 

m -- addr 

CVECTOR 

xxx (bO .. 

. bN count ■ 


xxx: ( 

m — addr 


UMOVE is a "universal" memory move. It takes 
the block of memory n bytes long at addrl and 
copies it to memory location addr2. UMOVE 
correctly uses either CMOVE or <CM0VE. 

(at compile time) 

(at run time) 

If compiling, the sequence ccc (delimited by 
the trailing ") is compiled into the dictionary 
as a string: 

| len I c I c I c I ... I c I 
(at compile time) 

(at execution time) 

Takes the string on top of the stack and 
compiles it into the dictionary with the name 
xxx. When xxx is later executed, the address 
of the string is pushed onto the'Stack. 

Reserves space for a string of length n. 

When xxx is later executed, the address of the 
string is pushed onto the stack. 

Takes the string on top of the stack and sends 
it to the current output device. 

Takes the string at second on stack and stores 
it at the address on top of stack. 

Takes $2 and concatenates it with $1, leaving 
$3 at PAD. 

Returns the leftmost "n" characters of $1 as 

$ 2 . 

Returns the rightmost "n" characters of SI as 

$ 2 . 

Returns $2 of length u starting with the nth 
character of $ 1 . 

Returns the length of the specified string. 
Returns the ASCII value of the first character 
of the specified string. 

Compares SI with S2 and returns a status flag. 

Compares two strings on top of the stack. 

Compares two strings on top of the stack. 

Compares two strings on top of the stack. 

As most string operations leave resultant 
strings at PAD, the word SAVES is used to 
temporarily move strings to PAD+512. 

Searches SI for first occurrence of S2. 

Returns the character position in SI if a 
match is found; otherwise, zero is returned. 
Takes the character "c" and makes it into a 
string of length one and stores it at PAD. 

Takes the double number d and converts it to 
its ASCII representation as $ at PAD. 

Takes the single length number n and converts 
it to its ASCII representation as S at PAD. 
Creates $2 as n copies of the first character 
of SI. 

#INS has three similar but different functions. 
If n is positive, it accepts a string of n or 
fewer characters from the terminal. If n is 
zero, it accepts up to 255 characters from the 
terminal. If n is negative, it returns only 
after accepting -n characters from the terminal. 
The resultant string is stored at PAD. 

Accepts a string of up to 255 characters from 
the terminal. 

Removes trailing blanks from $1 leaving new $2. 
Exchanges the contents of SI with S2. 


(compiling) 

(executing) 

When compiling, creates an array named xxx 
with n 16-bit elements numbered 0 thru n- 1 . 

Initial values are undefined. When executing, 
takes an argument, m, off the stack and leaves 
the address of element m of the array. 

(compiling) 

(executing) 

When compiling, creates a c-array named xxx 
with n 8 -bit elements numbered 0 thru n- 1 . 

Initial values are undefined. When executing, 
takes an argument, m, off the stack and leaves 
the address of element m of the c-array. 

(compi 1 ing) 

(executing) 

When compiling, creates a table named xxx but 
does not allot space. Elements are compiled in 
directly with , (comma). When executing, takes 
one argument, m off the stack and, assuming 
16-bit elements, leaves the address of element 
m of the table. 

(compiling) 

(executing) 

When compiling, creates a c-table named xxx 
but does not allot space. Elements are compiled 
in directly with C, (c-comma). When executing, 
takes one argument, m off the stack and, assuming 
8 -bit elements, leaves the address of element m 
of the c-table. 

(compiling) 

(executing) 

When compiling, creates a vector named xxx 
with count 16-bit elements numbered 0-N. nO is 
the initial value of element 0, nN is the 
initial value of element N, and so on. When 
executing, takes one argument, m, off the stack 
and leaves the address of element m on the stack. 
) (compiling) 

) (executing) 

When compiling, creates a c-vector named xxx 
with count 8 -bit elements numbered 0-N. bO is 
the initial value of element 0, bN is the 
initial value of element N, and so on. When 
executing, takes an argument, m, off the stack 
and leaves the address of element m on the stack. 


Double Number Extensions 


DVARIABLE 

xxx ( d — ) 

At compile time, creates a double number 


xxx:( -- addr ) 

variable xxx with the initial value d. At 
run time, xxx leaves the address of its value 
on the stack. 

DCONSTANT 

xxx ( d -- ) 

At compile time, creates a double number 


xxx:( — d ) 

constant xxx with the initial value d. At 
run time, xxx leaves the value d on the stack. 

D- 

( dl d2 - d3 ) 

Leaves dl-d2=d3. 

D 0 = 

( d -- flag) 

If d is equal to 0. leaves true flag; 
otherwise, leaves false flag. 

D= 

( dl d 2 — flag ) 

If dl equals d2, leaves true flag; otherwise, 
leaves false flag. 

D0< 

( d — flag ) 

If d is negative, leaves true flag; otherwise, 
leaves false flag. 

D< 

( dl d 2 -- flag ) 

If dl is less than d2, leaves true flag; other¬ 
wise, leaves false flag. 

D> 

( dl d 2 - flag ) 

If dl is greater than d2, leaves true flag; 
otherwise, leaves false flag. 

DMIN 

( dl d2 - d3 ) 

Leaves the minimum of dl and d2. 

DMAX 

( dl d2 - d3 ) 

Leaves the maximum of dl and d2. 

D>R 

( d - ) 

Sends the double number at top of stack to the 
return stack. 

DR> 

( - d ) 

Pulls the double number at too of the return 
stack to the stack. 

D, 

( d - ) 

Compiles the double number at top of stack 
into the dictionary. 

DU< 

( udl ud 2 — flag ) 

If the unsigned double number udl is less 
than the unsigned double number ud 2 , leaves a 
true flag; otherwise, leaves a false flag. 

M+ 

( dl n — d 2 ) 

Converts n to a double number and then sums 
with dl. 

High Resolution Text Output 

GCINIT 

( -- ) 

Initializes the graphic character output 
routines. This must be executed prior to using 
any other hi-res output words. 

GC. 

( n — ) 

Displays the single length number n at the 
current hi-res cursor location. 

GC.R 

( nl n 2 -- ) 

Displays the single length number nl right- 
justified in a field n 2 graphic characters 
wide. See .R . 

GCD.R 

( d n — ) 

Displays the double length number d right- 
justified in a field n graphic characters 
wide. See D.R . 

GCEMIT 

( c - ) 

Displays the text character c at the current 
hi-res cursor location. Three special 
characters are interpreted by GCEMIT. 

GCLEN 

( addr n -- len ) 

Scans the first n characters at addr and 
returns the number of characters that will 
actually be displayed on screen. 

GCR 

( - ) 

Repositions the hi-res cursor to the beginning 
of the next hi-res text line. See CR . 

GCLS 

( - ) 

Clears the hi-res display and repositions the 
cursor in the upper lefthand corner. 

GCSPACE 

( - ) 

Sends a space to the graphic character output 
routine. See SPACE . 

GCSPACES 

( n - ) 

Sends n spaces to the graphic character output 
routine. See SPACES . 

GCTYPE 

( addr n -- ) 

Sends the first n characters at addr to the 
graphic character output routine. See TYPE . 

GC" ccc" 

( - ) 

Sends the character string ccc (delimited by ") 
to the graphic character output routine. 

GCBKS 

( - ) 

Moves the hi-res cursor back one character 
position for overstriking or underlining. 

GCPOS 

( horz vert -- ) 

Positions the hi-res cursor to the coordinates 
specified. Note that the upper lefthand corner 
is 0 , 0 . 

GCS. 

( addr — ) 

Sends the string found at addr and preceded by 
a count byte to the graphic character output 
routine. See S. . 

SUPER 

( - ) 

Forces the graphic character output routine 
into the superscript mode (or out of the sub¬ 
script mode). See VMI below. May be performed 
within a string by the * character. 

SUB 

( - ) 

Forces the graphic character output routine 
into the subscript mode (or out of the super¬ 
script mode). See VMI below. May be performed 
within a string by the v character. 

VMI 

( n — ) 

The VMI command sets the number of eighths of 
characters to scroll up or down when either a 
SUPER or SUB command is issued. 

VMI # 

( -- addr ) 

A variable set by VMI. 

OSTRIKE 

( ON or OFF — ) 

If the OSTRIKE option is ON, characters are 
printed over top of the previous characters 
giving the impression of overstriking. 

GCBAS 

( -- addr ) 

A variable which contains the address of the 
character set displayed by GCEMIT. To change 
character sets, simply store the address of 
your new character set into this variable. 

GCLFT 

( -- addr ) 

A variable which holds the column position of 
the left margin. 

GCRGT 

( -- addr ) 

A variable which holds the column position of 
the right margin. 
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